Documentation/networking/netdev-features.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/netdev-features.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/netdev-features.rst
Extension
.rst
Size
8903 bytes
Lines
221
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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 main sets of features on each netdevice,
first and second are initialized by the driver:

 1. netdev->hw_features set contains features whose state may possibly
    be changed (enabled or disabled) for a particular device by user's
    request.  Drivers normally initialize this set before registration or
    in the ndo_init callback. Changes after registration should be made
    very carefully as other parts of the code may assume hw_features are
    static. At the very least changes must be made under rtnl_lock and
    the netdev instance lock, and followed by netdev_update_features().

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

On top of those three main sets, each netdev has:

 1. Sets which control features inherited by child devices (VLAN, MPLS,
    hw_enc for L3/L4 tunnels). These sets allow the driver to limit which
    netdev->features are propagated, in case HW cannot perform the offloads
    with the extra headers present.

 2. netdev->mangleid_features, TSO features which are supported only when
    IP ID field can be mangled (constant instead of incrementing) during TSO.

 3. netdev->gso_partial_features, additional TSO features which HW can
    support via NETIF_F_GSO_PARTIAL.

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.

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

Annotation

Implementation Notes