Commit 5cf47393 authored by Yohei Kojima's avatar Yohei Kojima Committed by Jakub Kicinski
Browse files

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: default avatarYohei Kojima <yk@y-koj.net>
Reviewed-by: default avatarJakub Kicinski <kuba@kernel.org>
Reviewed-by: default avatarSimon Horman <horms@kernel.org>
Link: https://patch.msgid.link/ef90a56965ca66e57aa177929ce3e10c5ca815fa.1772031974.git.yk@y-koj.net


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent f22b4e6f

Documentation/networking/ethtool-netlink.rst

+8 −4
Original line number Diff line number Diff line
@@ -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