Documentation/networking/netdevices.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/networking/netdevices.rst
Extension
.rst
Size
15836 bytes
Lines
445
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: operation-table or driver-model contract
Status
pattern implementation candidate

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

struct net_device_ops
---------------------

``ndos`` are called without holding the instance lock for most drivers.

"Ops locked" drivers will have most of the ``ndos`` invoked under
the instance lock.

struct ethtool_ops
------------------

For non-"ops locked" drivers ethtool_ops are executed under ``rtnl_lock``.

For "ops locked" drivers, ``ethtool_ops``, unlike ``ndos``, run under
the instance lock **only**. Drivers may request that ``rtnl_lock``
is held around specific operations (both SET and GET) by setting
appropriate bits in ``ethtool_ops::op_needs_rtnl`` (if the necessary
``ETHTOOL_OP_NEEDS_RTNL_*`` bit doesn't exist, just add it).
Commonly used core helpers which force drivers to selectively opt-in to
``rtnl_lock`` protection include ``netdev_update_features()``,
``netif_set_real_num_tx_queues()``, and phylink helpers.

struct netdev_stat_ops
----------------------

"qstat" ops are invoked under the instance lock for "ops locked" drivers,
and under rtnl_lock for all other drivers.

struct net_shaper_ops
---------------------

All net shaper callbacks are invoked while holding the netdev instance
lock. ``rtnl_lock`` may or may not be held.

Note that supporting net shapers automatically enables "ops locking".

struct netdev_queue_mgmt_ops
----------------------------

All queue management callbacks are invoked while holding the netdev instance
lock. ``rtnl_lock`` may or may not be held.

Note that supporting struct netdev_queue_mgmt_ops automatically enables
"ops locking".

Notifiers and netdev instance lock
----------------------------------

For device drivers that implement shaping or queue management APIs,
some of the notifiers (``enum netdev_cmd``) are running under the netdev
instance lock.

The following netdev notifiers are always run under the instance lock:
* ``NETDEV_XDP_FEAT_CHANGE``

For devices with locked ops, currently only the following notifiers are
running under the lock:
* ``NETDEV_CHANGE``
* ``NETDEV_CHANGENAME``
* ``NETDEV_REGISTER``
* ``NETDEV_UP``

The following notifiers are running without the lock:
* ``NETDEV_UNREGISTER``

There are no clear expectations for the remaining notifiers. Notifiers not on
the list may run with or without the instance lock, potentially even invoking
the same notifier type with and without the lock from different code paths.
The goal is to eventually ensure that all (or most, with a few documented
exceptions) notifiers run under the instance lock. Please extend this

Annotation

Implementation Notes