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, sdf@fomichev•me,
hramamurthy@google•com, kuniyu@amazon•com, jdamato@fastly•com,
Jakub Kicinski <kuba@kernel•org>
Subject: [PATCH net-next v2 7/8] docs: netdev: break down the instance locking info per ops struct
Date: Tue, 8 Apr 2025 12:59:54 -0700 [thread overview]
Message-ID: <20250408195956.412733-8-kuba@kernel.org> (raw)
In-Reply-To: <20250408195956.412733-1-kuba@kernel.org>
Explicitly list all the ops structs and what locking they provide.
Use "ops locked" as a term for drivers which have ops called under
the instance lock.
Acked-by: Stanislav Fomichev <sdf@fomichev•me>
Signed-off-by: Jakub Kicinski <kuba@kernel•org>
---
v2:
- an exception -> exceptions
v1: https://lore.kernel.org/20250407190117.16528-8-kuba@kernel.org
---
Documentation/networking/netdevices.rst | 54 +++++++++++++++++++------
1 file changed, 42 insertions(+), 12 deletions(-)
diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst
index d6357472d3f1..7ae28c5fb835 100644
--- a/Documentation/networking/netdevices.rst
+++ b/Documentation/networking/netdevices.rst
@@ -314,13 +314,8 @@ struct napi_struct synchronization rules
softirq
will be called with interrupts disabled by netconsole.
-struct netdev_queue_mgmt_ops synchronization rules
-==================================================
-
-All queue management ndo callbacks are holding netdev instance lock.
-
-RTNL and netdev instance lock
-=============================
+netdev instance lock
+====================
Historically, all networking control operations were protected by a single
global lock known as ``rtnl_lock``. There is an ongoing effort to replace this
@@ -328,10 +323,13 @@ global lock with separate locks for each network namespace. Additionally,
properties of individual netdev are increasingly protected by per-netdev locks.
For device drivers that implement shaping or queue management APIs, all control
-operations will be performed under the netdev instance lock. Currently, this
-instance lock is acquired within the context of ``rtnl_lock``. The drivers
-can also explicitly request instance lock to be acquired via
-``request_ops_lock``. In the future, there will be an option for individual
+operations will be performed under the netdev instance lock.
+Drivers can also explicitly request instance lock to be held during ops
+by setting ``request_ops_lock`` to true. Code comments and docs refer
+to drivers which have ops called under the instance lock as "ops locked".
+See also the documentation of the ``lock`` member of struct net_device.
+
+In the future, there will be an option for individual
drivers to opt out of using ``rtnl_lock`` and instead perform their control
operations directly under the netdev instance lock.
@@ -343,8 +341,40 @@ there are two sets of interfaces: ``dev_xxx`` and ``netif_xxx`` (e.g.,
acquiring the instance lock themselves, while the ``netif_xxx`` functions
assume that the driver has already acquired the instance lock.
+struct net_device_ops
+---------------------
+
+``ndos`` are called without holding the instance lock for most drivers.
+
+"Ops locked" drivers will have most of the ``ndos`` invoked under
+the instance lock.
+
+struct ethtool_ops
+------------------
+
+Similarly to ``ndos`` the instance lock is only held for select drivers.
+For "ops locked" drivers all ethtool ops without exceptions should
+be called under the instance lock.
+
+struct net_shaper_ops
+---------------------
+
+All net shaper callbacks are invoked while holding the netdev instance
+lock. ``rtnl_lock`` may or may not be held.
+
+Note that supporting net shapers automatically enables "ops locking".
+
+struct netdev_queue_mgmt_ops
+----------------------------
+
+All queue management callbacks are invoked while holding the netdev instance
+lock. ``rtnl_lock`` may or may not be held.
+
+Note that supporting struct netdev_queue_mgmt_ops automatically enables
+"ops locking".
+
Notifiers and netdev instance lock
-==================================
+----------------------------------
For device drivers that implement shaping or queue management APIs,
some of the notifiers (``enum netdev_cmd``) are running under the netdev
--
2.49.0
next prev parent reply other threads:[~2025-04-08 20:00 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-04-08 19:59 [PATCH net-next v2 0/8] net: depend on instance lock for queue related netlink ops Jakub Kicinski
2025-04-08 19:59 ` [PATCH net-next v2 1/8] net: avoid potential race between netdev_get_by_index_lock() and netns switch Jakub Kicinski
2025-04-08 19:59 ` [PATCH net-next v2 2/8] net: designate XSK pool pointers in queues as "ops protected" Jakub Kicinski
2025-04-08 19:59 ` [PATCH net-next v2 3/8] netdev: add "ops compat locking" helpers Jakub Kicinski
2025-04-08 19:59 ` [PATCH net-next v2 4/8] netdev: don't hold rtnl_lock over nl queue info get when possible Jakub Kicinski
2025-04-08 19:59 ` [PATCH net-next v2 5/8] xdp: double protect netdev->xdp_flags with netdev->lock Jakub Kicinski
2025-04-08 22:15 ` Harshitha Ramamurthy
2025-04-09 18:40 ` Martin KaFai Lau
2025-04-08 19:59 ` [PATCH net-next v2 6/8] netdev: depend on netdev->lock for xdp features Jakub Kicinski
2025-04-10 17:10 ` Kuniyuki Iwashima
2025-04-11 2:10 ` Jakub Kicinski
2025-04-11 2:23 ` Jakub Kicinski
2025-04-11 17:41 ` Stanislav Fomichev
2025-04-11 19:19 ` Jakub Kicinski
2025-04-11 2:36 ` Kuniyuki Iwashima
2025-04-08 19:59 ` Jakub Kicinski [this message]
2025-04-09 2:59 ` [PATCH net-next v2 7/8] docs: netdev: break down the instance locking info per ops struct Joe Damato
2025-04-10 6:01 ` Jacob Keller
2025-04-10 16:08 ` Jakub Kicinski
2025-04-10 22:35 ` Keller, Jacob E
2025-04-10 23:39 ` Jakub Kicinski
2025-04-11 21:26 ` Jacob Keller
2025-04-08 19:59 ` [PATCH net-next v2 8/8] netdev: depend on netdev->lock for qstats in ops locked drivers Jakub Kicinski
2025-04-10 5:23 ` Jacob Keller
2025-04-10 23:46 ` Jakub Kicinski
2025-04-11 21:29 ` Jacob Keller
2025-04-10 0:40 ` [PATCH net-next v2 0/8] net: depend on instance lock for queue related netlink ops 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=20250408195956.412733-8-kuba@kernel.org \
--to=kuba@kernel$(echo .)org \
--cc=andrew+netdev@lunn$(echo .)ch \
--cc=davem@davemloft$(echo .)net \
--cc=edumazet@google$(echo .)com \
--cc=horms@kernel$(echo .)org \
--cc=hramamurthy@google$(echo .)com \
--cc=jdamato@fastly$(echo .)com \
--cc=kuniyu@amazon$(echo .)com \
--cc=netdev@vger$(echo .)kernel.org \
--cc=pabeni@redhat$(echo .)com \
--cc=sdf@fomichev$(echo .)me \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox