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 10 struct net_device; 11 struct devlink; 12 struct netlink_ext_ack; 13 14 enum net_shaper_binding_type { 15 NET_SHAPER_BINDING_TYPE_NETDEV, 16 /* NET_SHAPER_BINDING_TYPE_DEVLINK_PORT */ 17 }; 18 19 struct net_shaper_binding { 20 enum net_shaper_binding_type type; 21 union { 22 struct net_device *netdev; 23 struct devlink *devlink; 24 }; 25 }; 26 27 struct 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 */ 44 struct 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 */ 102 struct 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 160