net: explain "protection types" for the instance lock

Try to define some terminology for which fields are protected
by which lock and how. Some fields are protected by both rtnl_lock
and instance lock which is hard to talk about without having
a "key phrase" to refer to a particular protection scheme.

"ops protected" fields are defined later in the series, one by one.

Add ASSERT_RTNL() to netdev_ops_assert_locked() for drivers
not other instance protection of ops. Hopefully it's not too
confusion that netdev_lock_ops() does not match the lock which
netdev_ops_assert_locked() will assert, exactly. The noun "ops"
is in a different place in the name, so I think it's acceptable...

Acked-by: Stanislav Fomichev <sdf@fomichev.me>
Link: https://patch.msgid.link/20250324224537.248800-5-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 55859c565f847166275ad5e0692553171048df40..2b91fb96a41141333234e99d2e59d6b9571313bd 100644 (file)
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -2496,19 +2496,35 @@ struct net_device {
         * Should always be taken using netdev_lock() / netdev_unlock() helpers.
         * Drivers are free to use it for other protection.
         *
-        * Protects:
+        * For the drivers that implement shaper or queue API, the scope
+        * of this lock is expanded to cover most ndo/queue/ethtool/sysfs
+        * operations. Drivers may opt-in to this behavior by setting
+        * @request_ops_lock.
+        *
+        * @lock protection mixes with rtnl_lock in multiple ways, fields are
+        * either:
+        *
+        * - simply protected by the instance @lock;
+        *
+        * - double protected - writers hold both locks, readers hold either;
+        *
+        * - ops protected - protected by the lock held around the NDOs
+        *   and other callbacks, that is the instance lock on devices for
+        *   which netdev_need_ops_lock() returns true, otherwise by rtnl_lock;
+        *
+        * - double ops protected - always protected by rtnl_lock but for
+        *   devices for which netdev_need_ops_lock() returns true - also
+        *   the instance lock.
+        *
+        * Simply protects:
         *      @gro_flush_timeout, @napi_defer_hard_irqs, @napi_list,
         *      @net_shaper_hierarchy, @reg_state, @threaded
         *
-        * Partially protects (writers must hold both @lock and rtnl_lock):
+        * Double protects:
         *      @up
         *
         * Also protects some fields in struct napi_struct.
         *
-        * For the drivers that implement shaper or queue API, the scope
-        * of this lock is expanded to cover most ndo/queue/ethtool/sysfs
-        * operations.
-        *
         * Ordering: take after rtnl_lock.
         */
        struct mutex            lock;

diff --git a/include/net/netdev_lock.h b/include/net/netdev_lock.h
index 689ffdfae50d717a2f6400e4c2f63ca7a6e1659b..efd302375ef2a19ac13410e37a4d4b2826b0fc67 100644 (file)
--- a/include/net/netdev_lock.h
+++ b/include/net/netdev_lock.h
@@ -5,6 +5,7 @@
 
 #include <linux/lockdep.h>
 #include <linux/netdevice.h>
+#include <linux/rtnetlink.h>
 
 static inline bool netdev_trylock(struct net_device *dev)
 {
@@ -51,6 +52,8 @@ static inline void netdev_ops_assert_locked(const struct net_device *dev)
 {
        if (netdev_need_ops_lock(dev))
                lockdep_assert_held(&dev->lock);
+       else
+               ASSERT_RTNL();
 }
 
 static inline int netdev_lock_cmp_fn(const struct lockdep_map *a,