[PATCH net-next 3/3] net_shaper: add some notes on re-parenting
From: Jakub Kicinski <kuba@kernel.org>
Date: 2026-07-24 21:08:02
Subsystem:
networking [general], the rest · Maintainers:
"David S. Miller", Eric Dumazet, Jakub Kicinski, Paolo Abeni, Linus Torvalds
Clarify the re-parenting expectations. Specifically that @delete on a queue removes it from the hierarchy which is a bit unusual in the overall API structure. IIRC the implicit delete behavior was introduced because otherwise it would not be possible to remove a queue from the hierarchy without changing at least one handle of the shapers. Normally "removal" is done by "adding" to the new parent, but "outside the hierarchy" does not have a parent we can point at. Signed-off-by: Jakub Kicinski <kuba@kernel.org> --- include/net/net_shaper.h | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-)
diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
index c14eb87efe5e..05cb625b0fe5 100644
--- a/include/net/net_shaper.h
+++ b/include/net/net_shaper.h@@ -107,7 +107,12 @@ struct net_shaper_ops { * The @leaves array's size is specified by @leaves_count. * * @node and @leaves may or may not already exist - * (see the "Implicit creation" note). + * (see the "Implicit creation" note). If @node already exists, + * the @leaves should be *added* to its children. In this case, + * the @leaves array only holds new/modified leaves, not the full list. + * + * Re-parenting @leaves is implemented by a @group call on a new parent. + * There's no explicit call to remove the children from the old parent. */ int (*group)(struct net_shaper_binding *binding, int leaves_count, const struct net_shaper *leaves,
@@ -128,6 +133,13 @@ struct net_shaper_ops { * * Removes the shaper configuration as identified by the given @handle * on the device specified by @binding, restoring the default behavior. + * + * Note that a @delete call on a NET_SHAPER_SCOPE_QUEUE shaper also + * implicitly removes the associated queue from the scheduling + * hierarchy. The driver must take care of that step. + * @delete calls on NET_SHAPER_SCOPE_NODE should not require any + * implicit re-parenting in the driver as core will re-parent the leaves + * first, before deleting the SCOPE_NODE shaper. */ int (*delete)(struct net_shaper_binding *binding, const struct net_shaper_handle *handle,
--
2.55.0