netdev-features.rst 6.9 KB

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