Jeff Garzik wrote:
commit 4901236cec047029b970261b95e47d6be60f523e
Author: Jeff Garzik [EMAIL PROTECTED]
Date: Fri Aug 10 15:52:06 2007 -0400
[ETHTOOL] Introduce -{get,set}_priv_flags, ETHTOOL_[GS]PFLAGS
Signed-off-by: Jeff Garzik [EMAIL PROTECTED]
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 netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
