net: mention the convention for .ndo_setup_tc()

qdisc_offload_dump_helper(), originated from commit 602f3baf2218
("net_sch: red: Add offload ability to RED qdisc"), is designed to that

    Whether RED is being offloaded is being determined every time dump
    action is being called because parent change of this qdisc could
    change its offload state but doesn't require any RED function to be
    called.

and returning -EOPNOTSUPP (for dump queries) does not mean "I don't have
any statistics", but "I don't offload this qdisc anymore". At least two
existing drivers did it wrong, so it is worth mentioning.

Signed-off-by: David Yang <mmyangfl@gmail.com>
Link: https://patch.msgid.link/20260507214054.2539790-1-mmyangfl@gmail.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 744ffa243501c70eb21da28c39af3410f2832dc2..e7af71491a475928b13bd17a97b1427a3a2f8dd1 100644 (file)
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1223,6 +1223,12 @@ struct netdev_net_notifier {
  *     tx queues stopped. This allows the netdevice to perform queue
  *     management safely.
  *
+ *     NB: Returning -EOPNOTSUPP for whatever commands means "this qdisc
+ *     is not offloaded (anymore, offloading may have silently stopped)",
+ *     and the offloading flag is cleared. Notably, this is also true for
+ *     dump queries (e.g. TC_*_STATS commands). If the underlying device does
+ *     not report any statistics but is still offloading, return 0 instead.
+ *
  *     Fiber Channel over Ethernet (FCoE) offload functions.
  * int (*ndo_fcoe_enable)(struct net_device *dev);
  *     Called when the FCoE protocol stack wants to start using LLD for FCoE