github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-07-27 17:47:41 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: net: netdevices: small fixes and clarifications

Browse Source 
A handful of unrelated nits:

 - free_netdevice() does not exist; replace two stray references
   with free_netdev().
 - The simple-driver probe example fell through into err_undo after
   register_netdev() success; add return 0 for clarity.
 - Clarify the netdev_priv() paragraph: "(netdev_priv())" was easy
   to misread as the thing that needs explicit freeing; spell out
   that it refers to extra pointers stored in the device private
   struct.
 - ndo_setup_tc synchronization note: TC_SETUP_BLOCK / TC_SETUP_FT
   actually run under block->cb_lock, not "NFT locks", and rtnl_lock
   may or may not be held depending on path.
 - ->lltx guidance reads as very outdated, it's not really deprecated.
   I suspect people may have been trying to use it for HW drivers
   in the past but I can't think of such a case in the last decade.

Acked-by: Stanislav Fomichev <sdf@fomichev.me>
Link: https://patch.msgid.link/20260526160151.2793354-2-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Jakub Kicinski 2026-05-26 09:01:42 -07:00
parent d44646fc9e
commit ea50122e45
1 changed files with 17 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Documentation/networking/netdevices.rst
View File

@ -21,13 +21,14 @@ by free_netdev(). This is required to handle the pathological case cleanly
alloc_netdev_mqs() / alloc_netdev() reserve extra space for driver
private data which gets freed when the network device is freed. If
separately allocated data is attached to the network device
(netdev_priv()) then it is up to the module exit handler to free that.
(extra pointers stored in the device private struct) then it is up
to the module exit handler to free that.
There are two groups of APIs for registering struct net_device.
First group can be used in normal contexts where ``rtnl_lock`` is not already
held: register_netdev(), unregister_netdev().
Second group can be used when ``rtnl_lock`` is already held:
register_netdevice(), unregister_netdevice(), free_netdevice().
register_netdevice(), unregister_netdevice(), free_netdev().
Simple drivers
--------------
@ -58,6 +59,7 @@ the register_netdev(), and unregister_netdev() functions:
goto err_undo;
/* net_device is visible to the user! */
return 0;
err_undo:
/* ... undo the device setup ... */
@ -73,7 +75,7 @@ the register_netdev(), and unregister_netdev() functions:
Note that after calling register_netdev() the device is visible in the system.
Users can open it and start sending / receiving traffic immediately,
or run any other callback, so all initialization must be done prior to
or run any other callback, so all initialization must be **complete** prior to
registration.
unregister_netdev() closes the device and waits for all users to be done
@ -157,7 +159,7 @@ register_netdevice() fails. The callback may be invoked with or without
There is no explicit constructor callback, driver "constructs" the private
netdev state after allocating it and before registration.
Setting struct net_device.needs_free_netdev makes core call free_netdevice()
Setting struct net_device.needs_free_netdev makes core call free_netdev()
automatically after unregister_netdevice() when all references to the device
are gone. It only takes effect after a successful call to register_netdevice()
so if register_netdevice() fails driver is responsible for calling
@ -256,7 +258,7 @@ ndo_eth_ioctl:
lock if the driver implements queue management or shaper API.
Context: process
ndo_get_stats:
ndo_get_stats / ndo_get_stats64:
Synchronization: RCU (can be called concurrently with the stats
update path).
Context: atomic (can't sleep under RCU)
@ -264,12 +266,9 @@ ndo_get_stats:
ndo_start_xmit:
Synchronization: __netif_tx_lock spinlock.
When the driver sets dev->lltx this will be
called without holding netif_tx_lock. In this case the driver
has to lock by itself when needed.
The locking there should also properly protect against
set_rx_mode. WARNING: use of dev->lltx is deprecated.
Don't use it for new drivers.
When the driver sets dev->lltx this will be called without holding
netif_tx_lock. dev->lltx is meant for software drivers only, since
they often have no per-queue state.
Context: Process with BHs disabled or BH (timer),
will be called with interrupts disabled by netconsole.
@ -304,11 +303,15 @@ ndo_change_rx_flags:
lock if the driver implements queue management or shaper API.
ndo_setup_tc:
``TC_SETUP_BLOCK`` and ``TC_SETUP_FT`` are running under NFT locks
(i.e. no ``rtnl_lock`` and no device instance lock). The rest of
``tc_setup_type`` types run under netdev instance lock if the driver
Locking depends on ``tc_setup_type``. For most types the callback
is invoked under ``rtnl_lock`` and netdev instance lock if the driver
implements queue management or shaper API.
For ``TC_SETUP_BLOCK`` and ``TC_SETUP_FT`` ``rtnl_lock`` may or
may not be held, and the netdev instance lock is not held.
``TC_SETUP_BLOCK`` runs under ``block->cb_lock`` and ``TC_SETUP_FT``
runs under ``flowtable->flow_block_lock``.
Most ndo callbacks not specified in the list above are running
under ``rtnl_lock``. In addition, netdev instance lock is taken as well if
the driver implements queue management or shaper API.