^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Netdev features mess and how to get out from it alive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Author:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Michał Mirosław <mirq-linux@rere.qmqm.pl>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Part I: Feature sets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Long gone are the days when a network card would just take and give packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) verbatim. Today's devices add multiple features and bugs (read: offloads)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) that relieve an OS of various tasks like generating and checking checksums,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) splitting packets, classifying them. Those capabilities and their state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) are commonly referred to as netdev features in Linux kernel world.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) There are currently three sets of features relevant to the driver, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) one used internally by network core:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 1. netdev->hw_features set contains features whose state may possibly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) be changed (enabled or disabled) for a particular device by user's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) request. This set should be initialized in ndo_init callback and not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) changed later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 2. netdev->features set contains features which are currently enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) for a device. This should be changed only by network core or in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) error paths of ndo_set_features callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 3. netdev->vlan_features set contains features whose state is inherited
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) by child VLAN devices (limits netdev->features set). This is currently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) used for all VLAN devices whether tags are stripped or inserted in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) hardware or software.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 4. netdev->wanted_features set contains feature set requested by user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) This set is filtered by ndo_fix_features callback whenever it or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) some device-specific conditions change. This set is internal to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) networking core and should not be referenced in drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) Part II: Controlling enabled features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) When current feature set (netdev->features) is to be changed, new set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) is calculated and filtered by calling ndo_fix_features callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) and netdev_fix_features(). If the resulting set differs from current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) set, it is passed to ndo_set_features callback and (if the callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) returns success) replaces value stored in netdev->features.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) NETDEV_FEAT_CHANGE notification is issued after that whenever current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) set might have changed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) The following events trigger recalculation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 1. device's registration, after ndo_init returned success
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 2. user requested changes in features state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 3. netdev_update_features() is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) ndo_*_features callbacks are called with rtnl_lock held. Missing callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) are treated as always returning success.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) A driver that wants to trigger recalculation must do so by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) netdev_update_features() while holding rtnl_lock. This should not be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) from ndo_*_features callbacks. netdev->features should not be modified by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) driver except by means of ndo_fix_features callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) Part III: Implementation hints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) * ndo_fix_features:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) All dependencies between features should be resolved here. The resulting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) set can be reduced further by networking core imposed limitations (as coded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) in netdev_fix_features()). For this reason it is safer to disable a feature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) when its dependencies are not met instead of forcing the dependency on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) This callback should not modify hardware nor driver state (should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) stateless). It can be called multiple times between successive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) ndo_set_features calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) Callback must not alter features contained in NETIF_F_SOFT_FEATURES or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) NETIF_F_NEVER_CHANGE sets. The exception is NETIF_F_VLAN_CHALLENGED but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) care must be taken as the change won't affect already configured VLANs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * ndo_set_features:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Hardware should be reconfigured to match passed feature set. The set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) should not be altered unless some error condition happens that can't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) be reliably detected in ndo_fix_features. In this case, the callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) should update netdev->features to match resulting hardware state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) Errors returned are not (and cannot be) propagated anywhere except dmesg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) (Note: successful return is zero, >0 means silent error.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Part IV: Features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) For current list of features, see include/linux/netdev_features.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) This section describes semantics of some of them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) * Transmit checksumming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) For complete description, see comments near the top of include/linux/skbuff.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Note: NETIF_F_HW_CSUM is a superset of NETIF_F_IP_CSUM + NETIF_F_IPV6_CSUM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) It means that device can fill TCP/UDP-like checksum anywhere in the packets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) whatever headers there might be.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) * Transmit TCP segmentation offload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) NETIF_F_TSO_ECN means that hardware can properly split packets with CWR bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) set, be it TCPv4 (when NETIF_F_TSO is enabled) or TCPv6 (NETIF_F_TSO6).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) * Transmit UDP segmentation offload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) NETIF_F_GSO_UDP_L4 accepts a single UDP header with a payload that exceeds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) gso_size. On segmentation, it segments the payload on gso_size boundaries and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) replicates the network and UDP headers (fixing up the last one if less than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) gso_size).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) * Transmit DMA from high memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) On platforms where this is relevant, NETIF_F_HIGHDMA signals that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ndo_start_xmit can handle skbs with frags in high memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) * Transmit scatter-gather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Those features say that ndo_start_xmit can handle fragmented skbs:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) NETIF_F_SG --- paged skbs (skb_shinfo()->frags), NETIF_F_FRAGLIST ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) chained skbs (skb->next/prev list).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) * Software features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Features contained in NETIF_F_SOFT_FEATURES are features of networking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) stack. Driver should not change behaviour based on them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) * LLTX driver (deprecated for hardware drivers)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) NETIF_F_LLTX is meant to be used by drivers that don't need locking at all,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) e.g. software tunnels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) This is also used in a few legacy drivers that implement their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) own locking, don't use it for new (hardware) drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) * netns-local device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) NETIF_F_NETNS_LOCAL is set for devices that are not allowed to move between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) network namespaces (e.g. loopback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Don't use it in drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) * VLAN challenged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) NETIF_F_VLAN_CHALLENGED should be set for devices which can't cope with VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) headers. Some drivers set this because the cards can't handle the bigger MTU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) [FIXME: Those cases could be fixed in VLAN code by allowing only reduced-MTU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) VLANs. This may be not useful, though.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) * rx-fcs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) This requests that the NIC append the Ethernet Frame Checksum (FCS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) to the end of the skb data. This allows sniffers and other tools to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) read the CRC recorded by the NIC on receipt of the packet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) * rx-all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) This requests that the NIC receive all possible frames, including errored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) frames (such as bad FCS, etc). This can be helpful when sniffing a link with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) bad packets on it. Some NICs may receive more packets if also put into normal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) PROMISC mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) * rx-gro-hw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) This requests that the NIC enables Hardware GRO (generic receive offload).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Hardware GRO is basically the exact reverse of TSO, and is generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) stricter than Hardware LRO. A packet stream merged by Hardware GRO must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) be re-segmentable by GSO or TSO back to the exact original packet stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Hardware GRO is dependent on RXCSUM since every packet successfully merged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) by hardware must also have the checksum verified by hardware.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags