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>

diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst
index 93e06e8d51a9ca08cd9a838301f327488422ff79..60492d4df2ee89450442c5d094898c3c84f22621 100644 (file)
--- 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.