[PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[Yohei Kojima]

Clarify the bit-by-bit bitset format's behavior around mandatory
attributes and bit identification. More specifically, the following
changes are made:

* Rephrase a misleading sentence which implies name and index are
  mutually exclusive
* Describe that ETHTOOL_A_BITSET_BITS nest is mandatory
* Describe that a request fails if inconsistent identifiers are given

Signed-off-by: Yohei Kojima <yk@y-koj.net>
---
Current ethtool-netlink documentation doesn't describe several behavior
around bit-by-bit bitset, which makes it hard to develop a ethtool
library without digging into the kernel code. This patch eases the gap
between the kernel behavior and the documentation by adding descriptions
around the mandatory attribute and bit identification.

ChangeLog
=========
v2 (this version):
* Minimize the diff for ease of review
v1: https://lore.kernel.org/lkml/e9ea0fe8bf7935d6439e4dc883414b685afbaf58.1770045398.git.yk@y-koj.net/

---
 Documentation/networking/ethtool-netlink.rst | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index af56c304cef4..32179168eb73 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -96,7 +96,7 @@ For short bitmaps of (reasonably) fixed length, standard ``NLA_BITFIELD32``
 type is used. For arbitrary length bitmaps, ethtool netlink uses a nested
 attribute with contents of one of two forms: compact (two binary bitmaps
 representing bit values and mask of affected bits) and bit-by-bit (list of
-bits identified by either index or name).
+bits identified by index or name).
 
 Verbose (bit-by-bit) bitsets allow sending symbolic names for bits together
 with their values which saves a round trip (when the bitset is passed in a
@@ -156,12 +156,16 @@ Bit-by-bit form: nested (bitset) attribute contents:
  | | | ``ETHTOOL_A_BITSET_BIT_VALUE`` | flag   | present if bit is set       |
  +-+-+--------------------------------+--------+-----------------------------+
 
-Bit size is optional for bit-by-bit form. ``ETHTOOL_A_BITSET_BITS`` nest can
+For bit-by-bit form, ``ETHTOOL_A_BITSET_SIZE`` is optional, and
+``ETHTOOL_A_BITSET_BITS`` is mandatory. ``ETHTOOL_A_BITSET_BITS`` nest can
 only contain ``ETHTOOL_A_BITSET_BITS_BIT`` attributes but there can be an
 arbitrary number of them.  A bit may be identified by its index or by its
 name. When used in requests, listed bits are set to 0 or 1 according to
-``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved. A request fails if
-index exceeds kernel bit length or if name is not recognized.
+``ETHTOOL_A_BITSET_BIT_VALUE``, the rest is preserved.
+
+A request fails if index exceeds kernel bit length or if name is not
+recognized. If both name and index are set, the request will fail if they
+point to different bits.
 
 When ``ETHTOOL_A_BITSET_NOMASK`` flag is present, bitset is interpreted as
 a simple bitmap. ``ETHTOOL_A_BITSET_BIT_VALUE`` attributes are not used in
-- 
2.52.0

Re: [PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[Paolo Abeni]

On 2/7/26 11:25 AM, Yohei Kojima wrote:
> Clarify the bit-by-bit bitset format's behavior around mandatory
> attributes and bit identification. More specifically, the following
> changes are made:
> 
> * Rephrase a misleading sentence which implies name and index are
>   mutually exclusive
> * Describe that ETHTOOL_A_BITSET_BITS nest is mandatory
> * Describe that a request fails if inconsistent identifiers are given
> 
> Signed-off-by: Yohei Kojima <yk@y-koj.net>
> ---
> Current ethtool-netlink documentation doesn't describe several behavior
> around bit-by-bit bitset, which makes it hard to develop a ethtool
> library without digging into the kernel code. This patch eases the gap
> between the kernel behavior and the documentation by adding descriptions
> around the mandatory attribute and bit identification.

This needs review by someone provided with English natural language
skills far better than mine. I'm wrapping the net-next PR right now;
this has to be deferred after the merge window, I'm sorry.

/P

Re: [PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[Jakub Kicinski]

On Sat,  7 Feb 2026 19:25:38 +0900 Yohei Kojima wrote:
> Clarify the bit-by-bit bitset format's behavior around mandatory
> attributes and bit identification. More specifically, the following
> changes are made:
> 
> * Rephrase a misleading sentence which implies name and index are
>   mutually exclusive
> * Describe that ETHTOOL_A_BITSET_BITS nest is mandatory
> * Describe that a request fails if inconsistent identifiers are given
> 
> Signed-off-by: Yohei Kojima <yk@y-koj.net>

I'm no native speaker but FWIW:

Reviewed-by: Jakub Kicinski <kuba@kernel.org>

Re: [PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[Yohei Kojima]

On Wed, Feb 11, 2026 at 12:55:55PM +0100, Paolo Abeni wrote:
> On 2/7/26 11:25 AM, Yohei Kojima wrote:
> > Clarify the bit-by-bit bitset format's behavior around mandatory
> > attributes and bit identification. More specifically, the following
> > changes are made:
> > 
> > * Rephrase a misleading sentence which implies name and index are
> >   mutually exclusive
> > * Describe that ETHTOOL_A_BITSET_BITS nest is mandatory
> > * Describe that a request fails if inconsistent identifiers are given
> > 
> > Signed-off-by: Yohei Kojima <yk@y-koj.net>
> > ---
> > Current ethtool-netlink documentation doesn't describe several behavior
> > around bit-by-bit bitset, which makes it hard to develop a ethtool
> > library without digging into the kernel code. This patch eases the gap
> > between the kernel behavior and the documentation by adding descriptions
> > around the mandatory attribute and bit identification.
> 
> This needs review by someone provided with English natural language
> skills far better than mine. I'm wrapping the net-next PR right now;
> this has to be deferred after the merge window, I'm sorry.

Thank you for the response. It's okay, I understand maintainers are
super busy during this period.

FYI I've received a Reviewed-by from Jakub, so I believe it's ready for
merge after the merge window.

Thank you,
Yohei

Re: [PATCH net-next v2] docs: ethtool: clarify the bit-by-bit bitset format description

[Simon Horman]

On Wed, Feb 11, 2026 at 12:55:55PM +0100, Paolo Abeni wrote:
> On 2/7/26 11:25 AM, Yohei Kojima wrote:
> > Clarify the bit-by-bit bitset format's behavior around mandatory
> > attributes and bit identification. More specifically, the following
> > changes are made:
> > 
> > * Rephrase a misleading sentence which implies name and index are
> >   mutually exclusive
> > * Describe that ETHTOOL_A_BITSET_BITS nest is mandatory
> > * Describe that a request fails if inconsistent identifiers are given
> > 
> > Signed-off-by: Yohei Kojima <yk@y-koj.net>
> > ---
> > Current ethtool-netlink documentation doesn't describe several behavior
> > around bit-by-bit bitset, which makes it hard to develop a ethtool
> > library without digging into the kernel code. This patch eases the gap
> > between the kernel behavior and the documentation by adding descriptions
> > around the mandatory attribute and bit identification.
> 
> This needs review by someone provided with English natural language
> skills far better than mine. I'm wrapping the net-next PR right now;
> this has to be deferred after the merge window, I'm sorry.

Hi Paolo,

It's my opinion that, from an English language perspective, the changes
in this patch match the description.

Reviewed-by: Simon Horman <horms@kernel.org>