Netdev features mess and how to get out from it alive

네 가지 기능 집합

현대 네트워크 장치는 체크섬 생성·검증, 패킷 분할, 분류 같은 작업을 하드웨어로 넘기는 여러 오프로드를 제공합니다. Linux에서는 이러한 능력과 현재 활성 상태를 통틀어 netdev feature라고 부릅니다.

드라이버가 직접 다루는 집합은 세 개이고 네트워크 코어 내부용 집합이 하나 더 있습니다. `netdev->hw_features`는 사용자가 장치별로 켜거나 끌 수 있는 기능이며 `ndo_init`에서 초기화한 뒤 바꾸지 않아야 합니다. `netdev->features`는 현재 실제로 켜진 기능으로, 네트워크 코어 또는 `ndo_set_features`의 오류 경로에서만 변경해야 합니다.

`netdev->vlan_features`는 자식 VLAN 장치가 상속할 수 있는 기능을 나타내며 자식의 `netdev->features`를 제한합니다. 태그를 하드웨어에서 처리하든 소프트웨어에서 처리하든 모든 VLAN 장치에 사용됩니다. `netdev->wanted_features`는 사용자가 요청한 집합이며 조건이 바뀔 때마다 `ndo_fix_features`가 필터링합니다. 이는 코어 내부 필드이므로 드라이버가 참조해서는 안 됩니다.

.. SPDX-License-Identifier: GPL-2.0

=====================================================
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 the days when a network card would just take and give packets
verbatim.  Today's devices add multiple features and bugs (read: offloads)
that relieve an OS of various tasks like generating and checking checksums,
splitting packets, classifying them.  Those capabilities and their state
are 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

활성 기능 재계산과 콜백

현재 `netdev->features`를 바꿀 때 코어는 새 집합을 계산한 뒤 `ndo_fix_features`와 `netdev_fix_features()`로 필터링합니다. 결과가 현재 집합과 다르면 `ndo_set_features`에 전달하고, 콜백이 성공하면 그 값으로 `netdev->features`를 교체합니다. 현재 집합이 바뀌었을 가능성이 있으면 이후 `NETDEV_FEAT_CHANGE` 알림을 냅니다.

재계산은 `ndo_init`가 성공한 뒤 장치를 등록할 때, 사용자가 기능 상태 변경을 요청할 때, 또는 `netdev_update_features()`를 호출할 때 일어납니다. 모든 `ndo_*_features` 콜백은 `rtnl_lock`을 잡은 상태로 호출되며, 콜백이 없으면 항상 성공한 것으로 취급합니다.

드라이버가 재계산을 요청하려면 `rtnl_lock`을 보유한 채 `netdev_update_features()`를 호출해야 합니다. `ndo_*_features` 콜백 안에서 이를 다시 호출해서는 안 되며, 드라이버는 `ndo_fix_features`의 반환값을 통한 경우 외에는 `netdev->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.

The 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.

A driver that wants 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와 ndo_set_features

`ndo_fix_features`에서는 기능 사이의 모든 의존성을 해결합니다. 코어의 `netdev_fix_features()`가 결과를 더 줄일 수 있으므로, 의존 조건이 충족되지 않을 때 다른 기능을 억지로 켜기보다 해당 기능을 끄는 쪽이 안전합니다.

이 콜백은 하드웨어나 드라이버 상태를 수정하지 않는 무상태 함수여야 합니다. 두 `ndo_set_features` 호출 사이에 여러 번 호출될 수 있습니다. `NETIF_F_SOFT_FEATURES` 또는 `NETIF_F_NEVER_CHANGE`에 속한 기능을 바꾸면 안 되며, 예외인 `NETIF_F_VLAN_CHALLENGED`도 이미 구성된 VLAN에는 변경이 반영되지 않음을 주의해야 합니다.

`ndo_set_features`는 전달받은 집합과 일치하도록 하드웨어를 재구성합니다. `ndo_fix_features`에서 신뢰성 있게 감지할 수 없는 오류가 생긴 경우가 아니면 집합을 바꾸지 않아야 합니다. 그런 오류에서는 실제 하드웨어 상태와 맞도록 `netdev->features`를 갱신합니다. 반환 오류는 `dmesg` 이외에는 전파할 곳이 없으며, 0은 성공이고 양수는 조용한 오류를 뜻합니다.

==============================

 * 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 it is 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 set
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 means silent error.)



Part IV: Features

주요 기능 비트의 의미

현재 전체 기능 목록은 `include/linux/netdev_features.h`에 있습니다. 송신 체크섬의 자세한 계약은 `include/linux/skbuff.h` 상단 주석을 따릅니다. `NETIF_F_HW_CSUM`은 `NETIF_F_IP_CSUM`과 `NETIF_F_IPV6_CSUM`의 상위 집합으로, 헤더 배열과 무관하게 패킷 안의 TCP/UDP 계열 체크섬을 하드웨어가 채울 수 있음을 뜻합니다.

TCP 분할에서는 `NETIF_F_TSO_ECN`이 CWR 비트가 설정된 TCPv4 또는 TCPv6 패킷도 올바르게 나눌 수 있음을 나타냅니다. 각각 `NETIF_F_TSO` 또는 `NETIF_F_TSO6`이 함께 활성화되어야 합니다. UDP 분할의 `NETIF_F_GSO_UDP_L4`는 `gso_size`보다 큰 페이로드와 단일 UDP 헤더를 받아 경계마다 페이로드를 자르고 네트워크·UDP 헤더를 복제하며 마지막 조각 크기도 보정합니다.

`NETIF_F_HIGHDMA`는 관련 플랫폼에서 `ndo_start_xmit`가 high memory의 fragment를 가진 skb를 처리할 수 있음을 뜻합니다. scatter-gather 기능 가운데 `NETIF_F_SG`는 `skb_shinfo()->frags`의 paged skb, `NETIF_F_FRAGLIST`는 `skb->next/prev` 목록으로 연결된 skb를 송신 함수가 처리할 수 있음을 나타냅니다.

`NETIF_F_SOFT_FEATURES`에 든 항목은 네트워크 스택 자체의 기능이므로 드라이버가 이를 보고 동작을 바꾸면 안 됩니다. `NETIF_F_VLAN_CHALLENGED`는 VLAN 헤더를 처리할 수 없는 장치에 설정합니다. 일부 장치는 큰 MTU를 처리하지 못해 이 비트를 사용하며, 문서는 VLAN 코드가 MTU를 줄인 VLAN만 허용하는 방식으로 고칠 가능성을 FIXME로 남깁니다.

`rx-fcs`는 NIC가 수신한 이더넷 FCS를 skb 데이터 끝에 붙이도록 요청하여 스니퍼가 NIC에 기록된 CRC를 읽게 합니다. `rx-all`은 잘못된 FCS를 포함한 오류 프레임까지 가능한 한 모두 받도록 요청합니다. 손상된 링크를 분석할 때 유용하며, 일부 NIC는 일반 PROMISC 모드도 함께 켜야 더 많은 패킷을 받을 수 있습니다.

`rx-gro-hw`는 하드웨어 Generic Receive Offload를 켭니다. 이는 기본적으로 TSO의 역방향이며 하드웨어 LRO보다 엄격합니다. 합쳐진 스트림은 GSO나 TSO로 정확히 원래 패킷 스트림으로 복원할 수 있어야 합니다. 하드웨어가 병합한 모든 패킷의 체크섬도 검증해야 하므로 `RXCSUM`에 의존합니다.

`hsr-tag-ins-offload`와 `hsr-tag-rm-offload`는 장치가 HSR 또는 PRP 태그를 자동 삽입·제거함을 나타냅니다. `hsr-fwd-offload`는 HSR 프레임을 포트 사이에서 하드웨어로 전달하고, `hsr-dup-offload`는 나가는 HSR 또는 PRP 프레임을 하드웨어에서 복제합니다. `netmem-tx`는 netmem 송신 지원을 나타내며 세부 사항은 `Documentation/networking/netmem.rst`에 있습니다.

=================

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 UDP segmentation offload

NETIF_F_GSO_UDP_L4 accepts a single UDP header with a payload that exceeds
gso_size. On segmentation, it segments the payload on gso_size boundaries and
replicates the network and UDP headers (fixing up the last one if less than
gso_size).

 * 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 features of networking
stack. Driver should not change behaviour based on them.

 * 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 useful, though.]

*  rx-fcs

This requests that the NIC append the Ethernet Frame Checksum (FCS)
to the end of the skb data.  This allows sniffers and other tools to
read the CRC recorded by the NIC on receipt of the packet.

*  rx-all

This requests that the NIC receive all possible frames, including errored
frames (such as bad FCS, etc).  This can be helpful when sniffing a link with
bad packets on it.  Some NICs may receive more packets if also put into normal
PROMISC mode.

*  rx-gro-hw

This requests that the NIC enables Hardware GRO (generic receive offload).
Hardware GRO is basically the exact reverse of TSO, and is generally
stricter than Hardware LRO.  A packet stream merged by Hardware GRO must
be re-segmentable by GSO or TSO back to the exact original packet stream.
Hardware GRO is dependent on RXCSUM since every packet successfully merged
by hardware must also have the checksum verified by hardware.

* hsr-tag-ins-offload

This should be set for devices which insert an HSR (High-availability Seamless
Redundancy) or PRP (Parallel Redundancy Protocol) tag automatically.

* hsr-tag-rm-offload

This should be set for devices which remove HSR (High-availability Seamless
Redundancy) or PRP (Parallel Redundancy Protocol) tags automatically.

* hsr-fwd-offload

This should be set for devices which forward HSR (High-availability Seamless
Redundancy) frames from one port to another in hardware.

* hsr-dup-offload

This should be set for devices which duplicate outgoing HSR (High-availability
Seamless Redundancy) or PRP (Parallel Redundancy Protocol) tags automatically
frames in hardware.

* netmem-tx

This should be set for devices which support netmem TX. See
Documentation/networking/netmem.rst