Comments

On Tue, 12 Jul 2011 21:01:30 +0200 (CEST) Michał Mirosław wrote:
> Signed-off-by: Michał Mirosław <mirq-linux@rere.qmqm.pl>> ---> > Please comment if something is unclear!> Apply otherwise. ;)> > ---> Documentation/networking/netdev-features.txt | 155 ++++++++++++++++++++++++++> 1 files changed, 155 insertions(+), 0 deletions(-)> > diff --git a/Documentation/networking/netdev-features.txt b/Documentation/networking/netdev-features.txt> new file mode 100644> index 0000000..9c209e6> --- /dev/null> +++ b/Documentation/networking/netdev-features.txt> @@ -0,0 +1,155 @@> +Netdev features mess and how to get out from it alive> +=====================================================> +> +Author:> + Michał Mirosław <mirq-linux@rere.qmqm.pl>> +> +> +> + Part I: Feature sets> +======================> +> +Long gone are days, when a network card would just take and give packets
Long gone are the days when
> +verbatim. Todays devices add multiple features and bugs (read: offloads)
Today's
> +that relieves OS of various tasks like generating and checking checksums,
relieve an OS
> +splitting packets, classifying them. Those capabilities and their state> +is commonly referred to as netdev features in Linux kernel world.
are
> +> +There are currently three sets of features relevant to the driver, and> +one used internally by network core:> +> + 1. netdev->hw_features set contains features whose state may possibly> + be changed (enabled or disabled) for a particular device by user's> + request. This set should be initialized in ndo_init callback and not> + changed later.> +> + 2. netdev->features set contains features which are currently enabled> + for a device. This should be changed only by network core or in> + error paths of ndo_set_features callback.> +> + 3. netdev->vlan_features set contains features whose state is inherited> + by child VLAN devices (limits netdev->features set). This is currently> + used for all VLAN devices whether tags are stripped or inserted in> + hardware or software.> +> + 4. netdev->wanted_features set contains feature set requested by user.> + This set is filtered by ndo_fix_features callback whenever it or> + some device-specific conditions change. This set is internal to> + networking core and should not be referenced in drivers.> +> +> +> + Part II: Controlling enabled features> +=======================================> +> +When current feature set (netdev->features) is to be changed, new set> +is calculated and filtered by calling ndo_fix_features callback> +and netdev_fix_features(). If the resulting set differs from current> +set, it is passed to ndo_set_features callback and (if the callback> +returns success) replaces value stored in netdev->features.> +NETDEV_FEAT_CHANGE notification is issued after that whenever current> +set might have changed.> +> +Following events trigger recalculation:
The following events ...
> + 1. device's registration, after ndo_init returned success> + 2. user requested changes in features state> + 3. netdev_update_features() is called> +> +ndo_*_features callbacks are called with rtnl_lock held. Missing callbacks> +are treated as always returning success.> +> +Driver wanting to trigger recalculation must do so by calling
A driver that wants to trigger ...
> +netdev_update_features() while holding rtnl_lock. This should not be done> +from ndo_*_features callbacks. netdev->features should not be modified by> +driver except by means of ndo_fix_features callback.> +> +> +> + Part III: Implementation hints> +================================> +> + * ndo_fix_features:> +> +All dependencies between features should be resolved here. The resulting> +set can be reduced further by networking core imposed limitations (as coded> +in netdev_fix_features()). For this reason its safer to disable a feature
it is
> +when its dependencies are not met instead of forcing the dependency on.> +> +This callback should not modify hardware nor driver state (should be> +stateless). It can be called multiple times between successive> +ndo_set_features calls.> +> +Callback must not alter features contained in NETIF_F_SOFT_FEATURES or> +NETIF_F_NEVER_CHANGE sets. The exception is NETIF_F_VLAN_CHALLENGED but> +care must be taken as the change won't affect already configured VLANs.> +> + * ndo_set_features:> +> +Hardware should be reconfigured to match passed feature set. The should not
The <what> should not
> +be altered unless some error condition happens that can't be reliably> +detected in ndo_fix_features. In this case, the callback should update> +netdev->features to match resulting hardware state. Errors returned are> +not (and cannot be) propagated anywhere except dmesg. (Note: successful> +return is zero, >0 is silent error.) > +> +> +> + Part IV: Features> +===================> +> +For current list of features, see include/linux/netdev_features.h.> +This section describes semantics of some of them.> +> + * Transmit checksumming> +> +For complete description, see comments near the top of include/linux/skbuff.h.> +> +Note: NETIF_F_HW_CSUM is a superset of NETIF_F_IP_CSUM + NETIF_F_IPV6_CSUM.> +It means that device can fill TCP/UDP-like checksum anywhere in the packets> +whatever headers there might be.> +> + * Transmit TCP segmentation offload> +> +NETIF_F_TSO_ECN means that hardware can properly split packets with CWR bit> +set, be it TCPv4 (when NETIF_F_TSO is enabled) or TCPv6 (NETIF_F_TSO6).> +> + * Transmit DMA from high memory> +> +On platforms where this is relevant, NETIF_F_HIGHDMA signals that> +ndo_start_xmit can handle skbs with frags in high memory.> +> + * Transmit scatter-gather> +> +Those features say that ndo_start_xmit can handle fragmented skbs:> +NETIF_F_SG --- paged skbs (skb_shinfo()->frags), NETIF_F_FRAGLIST ---> +chained skbs (skb->next/prev list).> +> + * Software features> +> +Features contained in NETIF_F_SOFT_FEATURES are a features of networking
^ drop "a"
> +stack. Driver should not change behaviour based on them.> +> + * LLTX driver (deprecated for hardware drivers)> +> +NETIF_F_LLTX should be set in drivers that implement their own locking in> +transmit path or don't need locking at all (e.g. software tunnels).> +In ndo_start_xmit, it is recommended to use a try_lock and return> +NETDEV_TX_LOCKED when the spin lock fails. The locking should also properly> +protect against other callbacks (the rules you need to find out).> +> +Don't use it for new drivers.> +> + * netns-local device> +> +NETIF_F_NETNS_LOCAL is set for devices that are not allowed to move between> +network namespaces (e.g. loopback).> +> +Don't use it in drivers.> +> + * VLAN challenged> +> +NETIF_F_VLAN_CHALLENGED should be set for devices which can't cope with VLAN> +headers. Some drivers set this because the cards can't handle the bigger MTU.> +[FIXME: Those cases could be fixed in VLAN code by allowing only reduced-MTU> +VLANs. This may be not usefull, though.]
useful
> +> --
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

diff --git a/Documentation/networking/netdev-features.txt b/Documentation/networking/netdev-features.txt
new file mode 100644
index 0000000..9c209e6--- /dev/null+++ b/Documentation/networking/netdev-features.txt@@ -0,0 +1,155 @@+Netdev features mess and how to get out from it alive+=====================================================++Author:+ Michał Mirosław <mirq-linux@rere.qmqm.pl>++++ Part I: Feature sets+======================++Long gone are days, when a network card would just take and give packets+verbatim. Todays devices add multiple features and bugs (read: offloads)+that relieves OS of various tasks like generating and checking checksums,+splitting packets, classifying them. Those capabilities and their state+is commonly referred to as netdev features in Linux kernel world.++There are currently three sets of features relevant to the driver, and+one used internally by network core:++ 1. netdev->hw_features set contains features whose state may possibly+ be changed (enabled or disabled) for a particular device by user's+ request. This set should be initialized in ndo_init callback and not+ changed later.++ 2. netdev->features set contains features which are currently enabled+ for a device. This should be changed only by network core or in+ error paths of ndo_set_features callback.++ 3. netdev->vlan_features set contains features whose state is inherited+ by child VLAN devices (limits netdev->features set). This is currently+ used for all VLAN devices whether tags are stripped or inserted in+ hardware or software.++ 4. netdev->wanted_features set contains feature set requested by user.+ This set is filtered by ndo_fix_features callback whenever it or+ some device-specific conditions change. This set is internal to+ networking core and should not be referenced in drivers.++++ Part II: Controlling enabled features+=======================================++When current feature set (netdev->features) is to be changed, new set+is calculated and filtered by calling ndo_fix_features callback+and netdev_fix_features(). If the resulting set differs from current+set, it is passed to ndo_set_features callback and (if the callback+returns success) replaces value stored in netdev->features.+NETDEV_FEAT_CHANGE notification is issued after that whenever current+set might have changed.++Following events trigger recalculation:+ 1. device's registration, after ndo_init returned success+ 2. user requested changes in features state+ 3. netdev_update_features() is called++ndo_*_features callbacks are called with rtnl_lock held. Missing callbacks+are treated as always returning success.++Driver wanting to trigger recalculation must do so by calling+netdev_update_features() while holding rtnl_lock. This should not be done+from ndo_*_features callbacks. netdev->features should not be modified by+driver except by means of ndo_fix_features callback.++++ Part III: Implementation hints+================================++ * ndo_fix_features:++All dependencies between features should be resolved here. The resulting+set can be reduced further by networking core imposed limitations (as coded+in netdev_fix_features()). For this reason its safer to disable a feature+when its dependencies are not met instead of forcing the dependency on.++This callback should not modify hardware nor driver state (should be+stateless). It can be called multiple times between successive+ndo_set_features calls.++Callback must not alter features contained in NETIF_F_SOFT_FEATURES or+NETIF_F_NEVER_CHANGE sets. The exception is NETIF_F_VLAN_CHALLENGED but+care must be taken as the change won't affect already configured VLANs.++ * ndo_set_features:++Hardware should be reconfigured to match passed feature set. The should not+be altered unless some error condition happens that can't be reliably+detected in ndo_fix_features. In this case, the callback should update+netdev->features to match resulting hardware state. Errors returned are+not (and cannot be) propagated anywhere except dmesg. (Note: successful+return is zero, >0 is silent error.) ++++ Part IV: Features+===================++For current list of features, see include/linux/netdev_features.h.+This section describes semantics of some of them.++ * Transmit checksumming++For complete description, see comments near the top of include/linux/skbuff.h.++Note: NETIF_F_HW_CSUM is a superset of NETIF_F_IP_CSUM + NETIF_F_IPV6_CSUM.+It means that device can fill TCP/UDP-like checksum anywhere in the packets+whatever headers there might be.++ * Transmit TCP segmentation offload++NETIF_F_TSO_ECN means that hardware can properly split packets with CWR bit+set, be it TCPv4 (when NETIF_F_TSO is enabled) or TCPv6 (NETIF_F_TSO6).++ * Transmit DMA from high memory++On platforms where this is relevant, NETIF_F_HIGHDMA signals that+ndo_start_xmit can handle skbs with frags in high memory.++ * Transmit scatter-gather++Those features say that ndo_start_xmit can handle fragmented skbs:+NETIF_F_SG --- paged skbs (skb_shinfo()->frags), NETIF_F_FRAGLIST ---+chained skbs (skb->next/prev list).++ * Software features++Features contained in NETIF_F_SOFT_FEATURES are a features of networking+stack. Driver should not change behaviour based on them.++ * LLTX driver (deprecated for hardware drivers)++NETIF_F_LLTX should be set in drivers that implement their own locking in+transmit path or don't need locking at all (e.g. software tunnels).+In ndo_start_xmit, it is recommended to use a try_lock and return+NETDEV_TX_LOCKED when the spin lock fails. The locking should also properly+protect against other callbacks (the rules you need to find out).++Don't use it for new drivers.++ * netns-local device++NETIF_F_NETNS_LOCAL is set for devices that are not allowed to move between+network namespaces (e.g. loopback).++Don't use it in drivers.++ * VLAN challenged++NETIF_F_VLAN_CHALLENGED should be set for devices which can't cope with VLAN+headers. Some drivers set this because the cards can't handle the bigger MTU.+[FIXME: Those cases could be fixed in VLAN code by allowing only reduced-MTU+VLANs. This may be not usefull, though.]+