Catch up various bits of documentation after the locking changes. Signed-off-by: Jakub Kicinski --- Documentation/networking/netdev-features.rst | 7 +++++++ Documentation/networking/netdevices.rst | 17 ++++++++++------- include/linux/ethtool.h | 10 ++++++++-- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/Documentation/networking/netdev-features.rst b/Documentation/networking/netdev-features.rst index 6293d47e5b09..f9e1f3921f53 100644 --- a/Documentation/networking/netdev-features.rst +++ b/Documentation/networking/netdev-features.rst @@ -76,6 +76,13 @@ netdev instance lock, that lock must be held as well. This should not be done from ndo_*_features callbacks. netdev->features should not be modified by driver except by means of ndo_fix_features callback. +For "ops locked" drivers (see Documentation/networking/netdevices.rst), +ethtool callbacks that may end up invoking netdev_update_features() must +opt back into rtnl_lock by setting the matching ETHTOOL_OP_NEEDS_RTNL_* +bit in ``ethtool_ops::op_needs_rtnl``. The ethtool core then keeps +rtnl_lock held across those SET callbacks so the contract above still +holds. + ndo_features_check is called for each skb before that skb is passed to ndo_start_xmit. Driver may perform any non-trivial checks (e.g. exact header geometry / length) and withdraw features like HW_CSUM or TSO, diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst index 60492d4df2ee..30a4219041d5 100644 --- a/Documentation/networking/netdevices.rst +++ b/Documentation/networking/netdevices.rst @@ -351,10 +351,6 @@ virtual and the physical device. To prevent deadlocks, the virtual device's lock must always be acquired before the physical device's (see ``netdev_nl_queue_create_doit``). -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. - Device drivers are encouraged to rely on the instance lock where possible. For the (mostly software) drivers that need to interact with the core stack, @@ -375,9 +371,16 @@ 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. +For non-"ops locked" drivers ethtool_ops are executed under ``rtnl_lock``. + +For "ops locked" drivers ``ethtool_ops``, unlike ``ndos``, run under +the instance lock **only**. Driver may request that ``rtnl_lock`` +is held around specific operations (both SET and GET) by setting +appropriate bits in ``ethtool_ops::op_needs_rtnl`` (if necessary +``ETHTOOL_OP_NEEDS_RTNL_*`` bit doesn't exist just add it). Commonly +used core helpers which force drivers to selectively opt-in to +``rtnl_lock`` protection include ``netdev_update_features()``, +``netif_set_real_num_*_queues()``, and phylink helpers. struct netdev_stat_ops ---------------------- diff --git a/include/linux/ethtool.h b/include/linux/ethtool.h index 35ee57a0e5fa..b62028eaf28e 100644 --- a/include/linux/ethtool.h +++ b/include/linux/ethtool.h @@ -1177,8 +1177,14 @@ struct kernel_ethtool_ts_info { * @get_mm_stats: Query the 802.3 MAC Merge layer statistics. * * All operations are optional (i.e. the function pointer may be set - * to %NULL) and callers must take this into account. Callers must - * hold the RTNL lock or netdev instance lock (see @op_needs_rtnl). + * to %NULL) and callers must take this into account. + * + * For traditional drivers callers hold ``rtnl_lock`` across the call. + * For "ops locked" drivers (see Documentation/networking/netdevices.rst) + * callers instead hold the netdev instance lock (``netdev_lock_ops``); + * ``rtnl_lock`` is additionally held only for callbacks for which + * the driver opts in via the matching ``ETHTOOL_OP_NEEDS_RTNL_*`` bit + * in @op_needs_rtnl. * * See the structures used by these operations for further documentation. * Note that for all operations using a structure ending with a zero- -- 2.54.0