From: Jakub Kicinski Date: Tue, 26 May 2026 16:01:42 +0000 (-0700) Subject: docs: net: netdevices: small fixes and clarifications X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ea50122e4520b05e45e3366cc4a8a9942f0c5ab9;p=thirdparty%2Flinux.git 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 Link: https://patch.msgid.link/20260526160151.2793354-2-kuba@kernel.org Signed-off-by: Jakub Kicinski --- 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.