From: Yohei Kojima Date: Wed, 25 Feb 2026 15:12:09 +0000 (+0900) Subject: docs: ethtool: clarify the bit-by-bit bitset format description X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5cf47393d96f211836ce98a22cebdf0eb8555413;p=thirdparty%2Flinux.git docs: ethtool: clarify the bit-by-bit bitset format description 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 Reviewed-by: Jakub Kicinski Reviewed-by: Simon Horman Link: https://patch.msgid.link/ef90a56965ca66e57aa177929ce3e10c5ca815fa.1772031974.git.yk@y-koj.net Signed-off-by: Jakub Kicinski --- diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index af56c304cef43..32179168eb732 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