diff options
| author | Jakub Kicinski <kuba@kernel.org> | 2026-05-26 09:01:42 -0700 |
|---|---|---|
| committer | Jakub Kicinski <kuba@kernel.org> | 2026-05-28 14:37:46 -0700 |
| commit | ea50122e4520b05e45e3366cc4a8a9942f0c5ab9 (patch) | |
| tree | 9e463df3b12d20b06a94df46f099dc548b300b07 /Documentation | |
| parent | d44646fc9eeb423ad50f3043f11f66f491d908a7 (diff) | |
| download | linux-next-history-ea50122e4520b05e45e3366cc4a8a9942f0c5ab9.tar.gz | |
docs: net: netdevices: small fixes and clarifications
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>
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/networking/netdevices.rst | 31 |
1 files changed, 17 insertions, 14 deletions
diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst index 93e06e8d51a9c..60492d4df2ee8 100644 --- a/Documentation/networking/netdevices.rst +++ b/Documentation/networking/netdevices.rst @@ -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. |