From: Jakub Kicinski <kuba@kernel.org>
To: davem@davemloft.net
Cc: netdev@vger.kernel.org, edumazet@google.com, pabeni@redhat.com,
andrew+netdev@lunn.ch, horms@kernel.org, corbet@lwn.net,
vladimir.oltean@nxp.com, willemb@google.com,
sdf.kernel@gmail.com, ecree.xilinx@gmail.com,
jesse.brandeburg@intel.com, linux-doc@vger.kernel.org,
Jakub Kicinski <kuba@kernel.org>
Subject: [PATCH net-next 01/10] docs: net: netdevices: small fixes and clarifications
Date: Tue, 26 May 2026 09:01:42 -0700 [thread overview]
Message-ID: <20260526160151.2793354-2-kuba@kernel.org> (raw)
In-Reply-To: <20260526160151.2793354-1-kuba@kernel.org>
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.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Documentation/networking/netdevices.rst | 31 ++++++++++++++-----------
1 file changed, 17 insertions(+), 14 deletions(-)
diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst
index 93e06e8d51a9..60492d4df2ee 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 @@ In that case the struct net_device registration is done using
goto err_undo;
/* net_device is visible to the user! */
+ return 0;
err_undo:
/* ... undo the device setup ... */
@@ -73,7 +75,7 @@ In that case the struct net_device registration is done using
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 @@ struct net_device synchronization rules
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 @@ struct net_device synchronization rules
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 @@ struct net_device synchronization rules
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.
--
2.54.0
next prev parent reply other threads:[~2026-05-26 16:02 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-26 16:01 [PATCH net-next 00/10] docs: net: updates for old and cobwebbed docs Jakub Kicinski
2026-05-26 16:01 ` Jakub Kicinski [this message]
2026-05-26 22:12 ` [PATCH net-next 01/10] docs: net: netdevices: small fixes and clarifications Stanislav Fomichev
2026-05-26 16:01 ` [PATCH net-next 02/10] docs: net: fix minor issues with driver guide Jakub Kicinski
2026-05-26 16:01 ` [PATCH net-next 03/10] docs: net: statistics: fix kernel-internal stats list Jakub Kicinski
2026-05-26 16:01 ` [PATCH net-next 04/10] docs: net: update devmem code examples Jakub Kicinski
2026-05-26 22:17 ` Stanislav Fomichev
2026-05-26 16:01 ` [PATCH net-next 05/10] docs: net: fix minor issues with the NAPI guide Jakub Kicinski
2026-05-26 16:01 ` [PATCH net-next 06/10] docs: net: refresh netdev feature guidance Jakub Kicinski
2026-05-26 18:41 ` Maxime Chevallier
2026-05-26 22:35 ` Jakub Kicinski
2026-05-27 7:53 ` Maxime Chevallier
2026-05-26 16:01 ` [PATCH net-next 07/10] docs: net: fix minor issues with checksum offloads Jakub Kicinski
2026-05-26 16:01 ` [PATCH net-next 08/10] docs: net: add Rx notes to the checksum guide Jakub Kicinski
2026-05-26 18:56 ` Willem de Bruijn
2026-05-26 16:01 ` [PATCH net-next 09/10] docs: net: render the checksum comment in checksum-offloads.rst Jakub Kicinski
2026-05-26 18:56 ` Willem de Bruijn
2026-05-26 16:01 ` [PATCH net-next 10/10] docs: net: fix minor issues with segmentation offloads Jakub Kicinski
2026-05-26 18:48 ` [PATCH net-next 00/10] docs: net: updates for old and cobwebbed docs Randy Dunlap
2026-05-26 22:37 ` Jakub Kicinski
2026-05-26 22:40 ` Jakub Kicinski
2026-05-27 0:51 ` Randy Dunlap
2026-05-27 1:15 ` Jakub Kicinski
2026-05-27 2:39 ` Randy Dunlap
2026-05-27 14:48 ` Jakub Kicinski
2026-05-28 22:10 ` patchwork-bot+netdevbpf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20260526160151.2793354-2-kuba@kernel.org \
--to=kuba@kernel.org \
--cc=andrew+netdev@lunn.ch \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=ecree.xilinx@gmail.com \
--cc=edumazet@google.com \
--cc=horms@kernel.org \
--cc=jesse.brandeburg@intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
--cc=sdf.kernel@gmail.com \
--cc=vladimir.oltean@nxp.com \
--cc=willemb@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.