projects/linux·blob master · refs

159 lines · 5.4 KiB

1/* SPDX-License-Identifier: GPL-2.0-or-later */
2
3#ifndef _NET_SHAPER_H_
4#define _NET_SHAPER_H_
5
6#include <linux/types.h>
7
8#include <uapi/linux/net_shaper.h>
9
10struct net_device;
11struct devlink;
12struct netlink_ext_ack;
13
14enum net_shaper_binding_type {
15 NET_SHAPER_BINDING_TYPE_NETDEV,
16 /* NET_SHAPER_BINDING_TYPE_DEVLINK_PORT */
17};
18
19struct net_shaper_binding {
20 enum net_shaper_binding_type type;
21 union {
22 struct net_device *netdev;
23 struct devlink *devlink;
24 };
25};
26
27struct net_shaper_handle {
28 enum net_shaper_scope scope;
29 u32 id;
30};
31
32/**
33 * struct net_shaper - represents a shaping node on the NIC H/W
34 * zeroed field are considered not set.
35 * @parent: Unique identifier for the shaper parent, usually implied
36 * @handle: Unique identifier for this shaper
37 * @metric: Specify if the rate limits refers to PPS or BPS
38 * @bw_min: Minimum guaranteed rate for this shaper
39 * @bw_max: Maximum peak rate allowed for this shaper
40 * @burst: Maximum burst for the peek rate of this shaper
41 * @priority: Scheduling priority for this shaper
42 * @weight: Scheduling weight for this shaper
43 */
44struct net_shaper {
45 struct net_shaper_handle parent;
46 struct net_shaper_handle handle;
47 enum net_shaper_metric metric;
48 u64 bw_min;
49 u64 bw_max;
50 u64 burst;
51 u32 priority;
52 u32 weight;
53
54 /* private: */
55 u32 leaves; /* accounted only for NODE scope */
56 bool valid;
57 struct rcu_head rcu;
58};
59
60/**
61 * struct net_shaper_ops - Operations on device H/W shapers
62 *
63 * The operations applies to either net_device and devlink objects.
64 * The initial shaping configuration at device initialization is empty:
65 * does not constraint the rate in any way.
66 * The network core keeps track of the applied user-configuration in
67 * the net_device or devlink structure.
68 * The operations are serialized via a per device lock.
69 *
70 * Device not supporting any kind of nesting should not provide the
71 * @group operation.
72 *
73 * Each shaper is uniquely identified within the device with a 'handle'
74 * comprising the shaper scope and a scope-specific id.
75 *
76 * Driver ops vs uAPI
77 * ------------------
78 * Members of the driver ops mirror the Netlink uAPI but driver calls do not
79 * map 1:1 to user calls. Drivers need to be careful when assuming that calls
80 * disallowed at the uAPI level will never be made at the driver level.
81 * The shaper core performs automatic reparenting and cleanup, generating
82 * additional calls. Notably:
83 *
84 * - @group calls in the driver facing API may have nodes as leaves (user is
85 * only allowed to construct groups with queues as leaves)
86 * - @group calls may update leaf's parent if the parent is about
87 * to be removed (re-parenting nodes explicitly is not supported in the uAPI)
88 *
89 * Implicit creation
90 * -----------------
91 * Shapers are created implicitly, meaning that @set and @group operations
92 * are called both for existing and new shapers. The driver has to infer
93 * whether the operation is an update or a creation by tracking the handles.
94 * Removal of shapers is explicit and done with a @delete call.
95 *
96 * The @set operation implicitly creates NET_SHAPER_SCOPE_NETDEV and
97 * NET_SHAPER_SCOPE_QUEUE shapers.
98 * The @group operation implicitly creates NET_SHAPER_SCOPE_NETDEV and
99 * NET_SHAPER_SCOPE_NODE shapers (the group shaper itself), as well as
100 * NET_SHAPER_SCOPE_QUEUE shapers (leaves).
101 */
102struct net_shaper_ops {
103 /**
104 * @group: create a scheduling group or add leaves
105 *
106 * Nest the @leaves shapers identified under the @node shaper.
107 * All the shapers belong to the device specified by @binding.
108 * The @leaves array's size is specified by @leaves_count.
109 *
110 * @node and @leaves may or may not already exist
111 * (see the "Implicit creation" note). If @node already exists,
112 * the @leaves should be *added* to its children. In this case,
113 * the @leaves array only holds new/modified leaves, not the full list.
114 *
115 * Re-parenting @leaves is implemented by a @group call on a new parent.
116 * There's no explicit call to remove the children from the old parent.
117 */
118 int (*group)(struct net_shaper_binding *binding, int leaves_count,
119 const struct net_shaper *leaves,
120 const struct net_shaper *node,
121 struct netlink_ext_ack *extack);
122
123 /**
124 * @set: Updates the specified shaper
125 *
126 * Updates or creates the @shaper on the device specified by @binding.
127 */
128 int (*set)(struct net_shaper_binding *binding,
129 const struct net_shaper *shaper,
130 struct netlink_ext_ack *extack);
131
132 /**
133 * @delete: Removes the specified shaper
134 *
135 * Removes the shaper configuration as identified by the given @handle
136 * on the device specified by @binding, restoring the default behavior.
137 *
138 * Note that a @delete call on a NET_SHAPER_SCOPE_QUEUE shaper also
139 * implicitly removes the associated queue from the scheduling
140 * hierarchy. The driver must take care of that step.
141 * @delete calls on NET_SHAPER_SCOPE_NODE should not require any
142 * implicit re-parenting in the driver as core will re-parent the leaves
143 * first, before deleting the SCOPE_NODE shaper.
144 */
145 int (*delete)(struct net_shaper_binding *binding,
146 const struct net_shaper_handle *handle,
147 struct netlink_ext_ack *extack);
148
149 /**
150 * @capabilities: get the shaper features supported by the device
151 *
152 * Fills the bitmask @cap with the supported capabilities for the
153 * specified @scope and device specified by @binding.
154 */
155 void (*capabilities)(struct net_shaper_binding *binding,
156 enum net_shaper_scope scope, unsigned long *cap);
157};
158
159#endif