Commit 10b518d4 authored by Michal Kubecek's avatar Michal Kubecek Committed by David S. Miller
Browse files

ethtool: netlink bitset handling 



The ethtool netlink code uses common framework for passing arbitrary
length bit sets to allow future extensions. A bitset can be a list (only
one bitmap) or can consist of value and mask pair (used e.g. when client
want to modify only some bits). A bitset can use one of two formats:
verbose (bit by bit) or compact.

Verbose format consists of bitset size (number of bits), list flag and
an array of bit nests, telling which bits are part of the list or which
bits are in the mask and which of them are to be set. In requests, bits
can be identified by index (position) or by name. In replies, kernel
provides both index and name. Verbose format is suitable for "one shot"
applications like standard ethtool command as it avoids the need to
either keep bit names (e.g. link modes) in sync with kernel or having to
add an extra roundtrip for string set request (e.g. for private flags).

Compact format uses one (list) or two (value/mask) arrays of 32-bit
words to store the bitmap(s). It is more suitable for long running
applications (ethtool in monitor mode or network management daemons)
which can retrieve the names once and then pass only compact bitmaps to
save space.

Userspace requests can use either format; ETHTOOL_FLAG_COMPACT_BITSETS
flag in request header tells kernel which format to use in reply.
Notifications always use compact format.

As some code uses arrays of unsigned long for internal representation and
some arrays of u32 (or even a single u32), two sets of parse/compose
helpers are introduced. To avoid code duplication, helpers for unsigned
long arrays are implemented as wrappers around helpers for u32 arrays.
There are two reasons for this choice: (1) u32 arrays are more frequent in
ethtool code and (2) unsigned long array can be always interpreted as an
u32 array on little endian 64-bit and all 32-bit architectures while we
would need special handling for odd number of u32 words in the opposite
direction.

Signed-off-by: default avatarMichal Kubecek <mkubecek@suse.cz>
Reviewed-by: default avatarFlorian Fainelli <f.fainelli@gmail.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 041b1c5d

Documentation/networking/ethtool-netlink.rst

+84 −0
Original line number Diff line number Diff line
@@ -76,6 +76,90 @@ of the flag should be interpreted the way the client expects. A client must 
not set flags it does not understand.





Bit sets

========



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).



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

request) or at least a second request (when the bitset is in a reply). This is

useful for one shot applications like traditional ethtool command. On the

other hand, long running applications like ethtool monitor (displaying

notifications) or network management daemons may prefer fetching the names

only once and using compact form to save message size. Notifications from

ethtool netlink interface always use compact form for bitsets.



A bitset can represent either a value/mask pair (``ETHTOOL_A_BITSET_NOMASK``

not set) or a single bitmap (``ETHTOOL_A_BITSET_NOMASK`` set). In requests

modifying a bitmap, the former changes the bit set in mask to values set in

value and preserves the rest; the latter sets the bits set in the bitmap and

clears the rest.



Compact form: nested (bitset) atrribute contents:



  ============================  ======  ============================

  ``ETHTOOL_A_BITSET_NOMASK``   flag    no mask, only a list

  ``ETHTOOL_A_BITSET_SIZE``     u32     number of significant bits

  ``ETHTOOL_A_BITSET_VALUE``    binary  bitmap of bit values

  ``ETHTOOL_A_BITSET_MASK``     binary  bitmap of valid bits

  ============================  ======  ============================



Value and mask must have length at least ``ETHTOOL_A_BITSET_SIZE`` bits

rounded up to a multiple of 32 bits. They consist of 32-bit words in host byte

order, words ordered from least significant to most significant (i.e. the same

way as bitmaps are passed with ioctl interface).



For compact form, ``ETHTOOL_A_BITSET_SIZE`` and ``ETHTOOL_A_BITSET_VALUE`` are

mandatory. ``ETHTOOL_A_BITSET_MASK`` attribute is mandatory if

``ETHTOOL_A_BITSET_NOMASK`` is not set (bitset represents a value/mask pair);

if ``ETHTOOL_A_BITSET_NOMASK`` is not set, ``ETHTOOL_A_BITSET_MASK`` is not

allowed (bitset represents a single bitmap.



Kernel bit set length may differ from userspace length if older application is

used on newer kernel or vice versa. If userspace bitmap is longer, an error is

issued only if the request actually tries to set values of some bits not

recognized by kernel.



Bit-by-bit form: nested (bitset) attribute contents:



 +------------------------------------+--------+-----------------------------+

 | ``ETHTOOL_A_BITSET_NOMASK``        | flag   | no mask, only a list        |

 +------------------------------------+--------+-----------------------------+

 | ``ETHTOOL_A_BITSET_SIZE``          | u32    | number of significant bits  |

 +------------------------------------+--------+-----------------------------+

 | ``ETHTOOL_A_BITSET_BITS``          | nested | array of bits               |

 +-+----------------------------------+--------+-----------------------------+

 | | ``ETHTOOL_A_BITSET_BITS_BIT+``   | nested | one bit                     |

 +-+-+--------------------------------+--------+-----------------------------+

 | | | ``ETHTOOL_A_BITSET_BIT_INDEX`` | u32    | bit index (0 for LSB)       |

 +-+-+--------------------------------+--------+-----------------------------+

 | | | ``ETHTOOL_A_BITSET_BIT_NAME``  | string | bit name                    |

 +-+-+--------------------------------+--------+-----------------------------+

 | | | ``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.



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

header. Semantics of value and mask depends on the attribute.





List of message types

=====================

include/uapi/linux/ethtool_netlink.h

+35 −0
Original line number Diff line number Diff line
@@ -50,6 +50,41 @@ enum { 
	ETHTOOL_A_HEADER_MAX = __ETHTOOL_A_HEADER_CNT - 1

};



/* bit sets */



enum {

	ETHTOOL_A_BITSET_BIT_UNSPEC,

	ETHTOOL_A_BITSET_BIT_INDEX,		/* u32 */

	ETHTOOL_A_BITSET_BIT_NAME,		/* string */

	ETHTOOL_A_BITSET_BIT_VALUE,		/* flag */



	/* add new constants above here */

	__ETHTOOL_A_BITSET_BIT_CNT,

	ETHTOOL_A_BITSET_BIT_MAX = __ETHTOOL_A_BITSET_BIT_CNT - 1

};



enum {

	ETHTOOL_A_BITSET_BITS_UNSPEC,

	ETHTOOL_A_BITSET_BITS_BIT,		/* nest - _A_BITSET_BIT_* */



	/* add new constants above here */

	__ETHTOOL_A_BITSET_BITS_CNT,

	ETHTOOL_A_BITSET_BITS_MAX = __ETHTOOL_A_BITSET_BITS_CNT - 1

};



enum {

	ETHTOOL_A_BITSET_UNSPEC,

	ETHTOOL_A_BITSET_NOMASK,		/* flag */

	ETHTOOL_A_BITSET_SIZE,			/* u32 */

	ETHTOOL_A_BITSET_BITS,			/* nest - _A_BITSET_BITS_* */

	ETHTOOL_A_BITSET_VALUE,			/* binary */

	ETHTOOL_A_BITSET_MASK,			/* binary */



	/* add new constants above here */

	__ETHTOOL_A_BITSET_CNT,

	ETHTOOL_A_BITSET_MAX = __ETHTOOL_A_BITSET_CNT - 1

};



/* generic netlink info */

#define ETHTOOL_GENL_NAME "ethtool"

#define ETHTOOL_GENL_VERSION 1

net/ethtool/Makefile

+1 −1
Original line number Diff line number Diff line
@@ -4,4 +4,4 @@ obj-y += ioctl.o common.o 


obj-$(CONFIG_ETHTOOL_NETLINK)	+= ethtool_nl.o



ethtool_nl-y	:= netlink.o
 
ethtool_nl-y	:= netlink.o bitset.o

net/ethtool/bitset.c

0 → 100644
+735 −0

File added.

Preview size limit exceeded, changes collapsed.

net/ethtool/bitset.h

0 → 100644
+28 −0
Original line number Diff line number Diff line 
/* SPDX-License-Identifier: GPL-2.0-only */



#ifndef _NET_ETHTOOL_BITSET_H

#define _NET_ETHTOOL_BITSET_H



typedef const char (*const ethnl_string_array_t)[ETH_GSTRING_LEN];



int ethnl_bitset_is_compact(const struct nlattr *bitset, bool *compact);

int ethnl_bitset_size(const unsigned long *val, const unsigned long *mask,

		      unsigned int nbits, ethnl_string_array_t names,

		      bool compact);

int ethnl_bitset32_size(const u32 *val, const u32 *mask, unsigned int nbits,

			ethnl_string_array_t names, bool compact);

int ethnl_put_bitset(struct sk_buff *skb, int attrtype,

		     const unsigned long *val, const unsigned long *mask,

		     unsigned int nbits, ethnl_string_array_t names,

		     bool compact);

int ethnl_put_bitset32(struct sk_buff *skb, int attrtype, const u32 *val,

		       const u32 *mask, unsigned int nbits,

		       ethnl_string_array_t names, bool compact);

int ethnl_update_bitset(unsigned long *bitmap, unsigned int nbits,

			const struct nlattr *attr, ethnl_string_array_t names,

			struct netlink_ext_ack *extack, bool *mod);

int ethnl_update_bitset32(u32 *bitmap, unsigned int nbits,

			  const struct nlattr *attr, ethnl_string_array_t names,

			  struct netlink_ext_ack *extack, bool *mod);



#endif /* _NET_ETHTOOL_BITSET_H */

CRA Git | Maintained and supported by SUSTech CRA and CCSE