Clarify the format and semantics of the bit-by-bit bitset by the
following changes:
* Explicitly describe the mandatory and optional fields in one paragraph
* Detail what happens if ETHTOOL_A_BITSET_NOMASK is set
* Clarify that users can set both BIT_INDEX and BIT_NAME fields

Signed-off-by: Yohei Kojima <yk@y-koj.net>
---
 Documentation/networking/ethtool-netlink.rst | 31 ++++++++++++--------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index af56c304cef4..e20f8b541a5b 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,17 +156,24 @@ 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
-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.
-
-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
-such case. Such bitset represents a bitmap with listed bits set and the rest
-zero.
+For bit-by-bit form, ``ETHTOOL_A_BITSET_BITS`` attribute is mandatory, and
+``ETHTOOL_A_BITSET_SIZE`` is optional. ``ETHTOOL_A_BITSET_BITS`` contains
+zero or more ``ETHTOOL_A_BITSET_BITS_BIT``, which must contain
+``ETHTOOL_A_BITSET_BIT_INDEX`` and/or ``ETHTOOL_A_BITSET_BIT_NAME``.
+``ETHTOOL_A_BITSET_BIT_VALUE`` is optional, and ignored if
+``ETHTOOL_A_BITSET_NOMASK`` is present.
+
+``ETHTOOL_A_BITSET_NOMASK`` specifies the semantics of the bitset. If
+``ETHTOOL_A_BITSET_NOMASK`` is present, the bitset represents a list of the
+enabled bits (e.g. all bits are unset if ``ETHTOOL_A_BITSET_BITS`` is empty).
+On the other hand, if ``ETHTOOL_A_BITSET_NOMASK`` is not present, the bitset
+represents a list of the masked (valid) bits, and
+``ETHTOOL_A_BITSET_BIT_VALUE`` is present iff the bit is set.
+
+``ETHTOOL_A_BITSET_BIT_INDEX`` and ``ETHTOOL_A_BITSET_BIT_NAME`` identify
+the bit in the bitset. If both are set, the index and the name must point
+to the same bit. A request fails if the index exceeds kernel bit length or
+the name is not recognized.
 
 In requests, application can use either form. Form used by kernel in reply is
 determined by ``ETHTOOL_FLAG_COMPACT_BITSETS`` flag in flags field of request
-- 
2.52.0

On Tue,  3 Feb 2026 00:17:19 +0900 Yohei Kojima wrote:
> Clarify the format and semantics of the bit-by-bit bitset by the
> following changes:
> * Explicitly describe the mandatory and optional fields in one paragraph
> * Detail what happens if ETHTOOL_A_BITSET_NOMASK is set
> * Clarify that users can set both BIT_INDEX and BIT_NAME fields

To be honest I'm not entirely sure which doc is easier to follow,
before or after this patch :(
-- 
pw-bot: cr

On Tue, Feb 03, 2026 at 07:53:38PM -0800, Jakub Kicinski wrote:
> On Tue,  3 Feb 2026 00:17:19 +0900 Yohei Kojima wrote:
> > Clarify the format and semantics of the bit-by-bit bitset by the
> > following changes:
> > * Explicitly describe the mandatory and optional fields in one paragraph
> > * Detail what happens if ETHTOOL_A_BITSET_NOMASK is set
> > * Clarify that users can set both BIT_INDEX and BIT_NAME fields
> 
> To be honest I'm not entirely sure which doc is easier to follow,
> before or after this patch :(

Thank you for the feedback. In the v2 patch, I'll focus on adding the
missing explanation rather than restructuring the entire paragraph.

Thank you,
Yohei