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

From: Jeff Garzik
Date: Fri Aug 10 2007 - 16:45:34 EST


Jeff Garzik wrote:
commit 4901236cec047029b970261b95e47d6be60f523e
Author: Jeff Garzik <jeff@xxxxxxxxxx>
Date: Fri Aug 10 15:52:06 2007 -0400

[ETHTOOL] Introduce ->{get,set}_priv_flags, ETHTOOL_[GS]PFLAGS
Signed-off-by: Jeff Garzik <jeff@xxxxxxxxxx>

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.

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/