Driver writer hints (was [PATCH 3/4] Add ETHTOOL_[GS]PFLAGS sub-ioctls)

Jeff Garzik
2007-08-10T20:45:31Z

Jeff Garzik wrote:
> commit 4901236cec047029b970261b95e47d6be60f523e
> Author: Jeff Garzik <jeff@garzik.org>
> Date: Fri Aug 10 15:52:06 2007 -0400
>
> [ETHTOOL] Introduce ->{get,set}_priv_flags, ETHTOOL_[GS]PFLAGS
>
> Signed-off-by: Jeff Garzik <jeff@garzik.org>
>
> include/linux/ethtool.h | 8 +++++++-
> net/core/ethtool.c | 38 ++++++++++++++++++++++++++++++++++++++
> 2 files changed, 45 insertions(+), 1 deletion(-)

This change permits driver writers to allow userspace to enable/disable
driver-specific boolean options on a per-interface basis. This is best
illustrated by describing how userland uses this:

(this is very similar to how the get-stats and self-test operations
currently work)

1) Userland issues ETHTOOL_GDRVINFO, to obtain the n_priv_flags value.

2) Userland issues ETHTOOL_GSTRINGS (ETH_SS_PRIV_FLAGS) to obtain an
array of strings. Each element in this array maps to a bit in the list
of driver-private flags. Array element #0 is the tag (name) for bit #0.
Array element #5 is the tag for bit #5. etc.

If we are getting (retrieving) flags:

3) Userland issues ETHTOOL_GPFLAGS, to obtain a 32-bit bitmap

4) Userland prints out a tag returned from ETHTOOL_GSTRINGS
for each bit set to one in the bitmap. If a bit is set,
but there is no string to describe it, that bit is ignored.
(i.e. a list of 5 strings is returned, but bit 24 is set)

If we are setting flags:

3) Userland issues ETHTOOL_GPFLAGS, to obtain 32-bit bitmap

4) Userland parses command line, which has a series of strings
in the format of "+option" (set flag) and "-option" (clear
flag).

5) Userland sets and clears bits in the 32-bit bitmap, by
matching the command line-supplied data with strings returned
by ETHTOOL_GSTRINGS.

6) If the bitmap has changed, send it back to the driver using
ETHTOOL_SPFLAGS.

In this way, you can see that the actual bit numbers are irrelevant, and
need not be a fixed part of the ABI. Everything is named-based.

This name-based stuff only applies to the private flags. The
ETHTOOL_[GS]FLAGS operations /do/ fix the bit numbers in stone, in the
ABI. There is no name list associated with ETHTOOL_[GS]FLAGS]. The
userland interface does, however, use names rather than bit numbers, for
ease of use.

Another attribute is worth pointing out at this point: ETHTOOL_SFLAGS
and ETHTOOL_SPFLAGS both permit atomic retrieval/setting of groups of
features all at once. IMO this is a nice addition to ethtool as well,
where previously you had to issue separate ioctls for each feature,
which might result in repeated NIC resets [depending on driver
implementation].

Get-flags and get-priv-flags are unpriveleged operations. Set-flags and
set-priv-flags require CAP_NET_ADMIN like other ethtool sub-ioctls.

Drivers should return -EINVAL if userland attempts to set an invariant
(read-only) flag to something other than its constant value.