xref: /linux/include/net/netdev_queues.h (revision c5288cda69ee2d8607f5026bd599a5cebf0ee783)
1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _LINUX_NET_QUEUES_H
3 #define _LINUX_NET_QUEUES_H
4 
5 #include <linux/netdevice.h>
6 
7 /* See the netdev.yaml spec for definition of each statistic */
8 struct netdev_queue_stats_rx {
9 	u64 bytes;
10 	u64 packets;
11 	u64 alloc_fail;
12 
13 	u64 hw_drops;
14 	u64 hw_drop_overruns;
15 
16 	u64 csum_unnecessary;
17 	u64 csum_none;
18 	u64 csum_bad;
19 
20 	u64 hw_gro_packets;
21 	u64 hw_gro_bytes;
22 	u64 hw_gro_wire_packets;
23 	u64 hw_gro_wire_bytes;
24 
25 	u64 hw_drop_ratelimits;
26 };
27 
28 struct netdev_queue_stats_tx {
29 	u64 bytes;
30 	u64 packets;
31 
32 	u64 hw_drops;
33 	u64 hw_drop_errors;
34 
35 	u64 csum_none;
36 	u64 needs_csum;
37 
38 	u64 hw_gso_packets;
39 	u64 hw_gso_bytes;
40 	u64 hw_gso_wire_packets;
41 	u64 hw_gso_wire_bytes;
42 
43 	u64 hw_drop_ratelimits;
44 
45 	u64 stop;
46 	u64 wake;
47 };
48 
49 /**
50  * struct netdev_stat_ops - netdev ops for fine grained stats
51  * @get_queue_stats_rx:	get stats for a given Rx queue
52  * @get_queue_stats_tx:	get stats for a given Tx queue
53  * @get_base_stats:	get base stats (not belonging to any live instance)
54  *
55  * Query stats for a given object. The values of the statistics are undefined
56  * on entry (specifically they are *not* zero-initialized). Drivers should
57  * assign values only to the statistics they collect. Statistics which are not
58  * collected must be left undefined.
59  *
60  * Queue objects are not necessarily persistent, and only currently active
61  * queues are queried by the per-queue callbacks. This means that per-queue
62  * statistics will not generally add up to the total number of events for
63  * the device. The @get_base_stats callback allows filling in the delta
64  * between events for currently live queues and overall device history.
65  * When the statistics for the entire device are queried, first @get_base_stats
66  * is issued to collect the delta, and then a series of per-queue callbacks.
67  * Only statistics which are set in @get_base_stats will be reported
68  * at the device level, meaning that unlike in queue callbacks, setting
69  * a statistic to zero in @get_base_stats is a legitimate thing to do.
70  * This is because @get_base_stats has a second function of designating which
71  * statistics are in fact correct for the entire device (e.g. when history
72  * for some of the events is not maintained, and reliable "total" cannot
73  * be provided).
74  *
75  * Device drivers can assume that when collecting total device stats,
76  * the @get_base_stats and subsequent per-queue calls are performed
77  * "atomically" (without releasing the rtnl_lock).
78  *
79  * Device drivers are encouraged to reset the per-queue statistics when
80  * number of queues change. This is because the primary use case for
81  * per-queue statistics is currently to detect traffic imbalance.
82  */
83 struct netdev_stat_ops {
84 	void (*get_queue_stats_rx)(struct net_device *dev, int idx,
85 				   struct netdev_queue_stats_rx *stats);
86 	void (*get_queue_stats_tx)(struct net_device *dev, int idx,
87 				   struct netdev_queue_stats_tx *stats);
88 	void (*get_base_stats)(struct net_device *dev,
89 			       struct netdev_queue_stats_rx *rx,
90 			       struct netdev_queue_stats_tx *tx);
91 };
92 
93 /**
94  * struct netdev_queue_mgmt_ops - netdev ops for queue management
95  *
96  * @ndo_queue_mem_size: Size of the struct that describes a queue's memory.
97  *
98  * @ndo_queue_mem_alloc: Allocate memory for an RX queue at the specified index.
99  *			 The new memory is written at the specified address.
100  *
101  * @ndo_queue_mem_free:	Free memory from an RX queue.
102  *
103  * @ndo_queue_start:	Start an RX queue with the specified memory and at the
104  *			specified index.
105  *
106  * @ndo_queue_stop:	Stop the RX queue at the specified index. The stopped
107  *			queue's memory is written at the specified address.
108  */
109 struct netdev_queue_mgmt_ops {
110 	size_t			ndo_queue_mem_size;
111 	int			(*ndo_queue_mem_alloc)(struct net_device *dev,
112 						       void *per_queue_mem,
113 						       int idx);
114 	void			(*ndo_queue_mem_free)(struct net_device *dev,
115 						      void *per_queue_mem);
116 	int			(*ndo_queue_start)(struct net_device *dev,
117 						   void *per_queue_mem,
118 						   int idx);
119 	int			(*ndo_queue_stop)(struct net_device *dev,
120 						  void *per_queue_mem,
121 						  int idx);
122 };
123 
124 /**
125  * DOC: Lockless queue stopping / waking helpers.
126  *
127  * The netif_txq_maybe_stop() and __netif_txq_completed_wake()
128  * macros are designed to safely implement stopping
129  * and waking netdev queues without full lock protection.
130  *
131  * We assume that there can be no concurrent stop attempts and no concurrent
132  * wake attempts. The try-stop should happen from the xmit handler,
133  * while wake up should be triggered from NAPI poll context.
134  * The two may run concurrently (single producer, single consumer).
135  *
136  * The try-stop side is expected to run from the xmit handler and therefore
137  * it does not reschedule Tx (netif_tx_start_queue() instead of
138  * netif_tx_wake_queue()). Uses of the ``stop`` macros outside of the xmit
139  * handler may lead to xmit queue being enabled but not run.
140  * The waking side does not have similar context restrictions.
141  *
142  * The macros guarantee that rings will not remain stopped if there's
143  * space available, but they do *not* prevent false wake ups when
144  * the ring is full! Drivers should check for ring full at the start
145  * for the xmit handler.
146  *
147  * All descriptor ring indexes (and other relevant shared state) must
148  * be updated before invoking the macros.
149  */
150 
151 #define netif_txq_try_stop(txq, get_desc, start_thrs)			\
152 	({								\
153 		int _res;						\
154 									\
155 		netif_tx_stop_queue(txq);				\
156 		/* Producer index and stop bit must be visible		\
157 		 * to consumer before we recheck.			\
158 		 * Pairs with a barrier in __netif_txq_completed_wake(). \
159 		 */							\
160 		smp_mb__after_atomic();					\
161 									\
162 		/* We need to check again in a case another		\
163 		 * CPU has just made room available.			\
164 		 */							\
165 		_res = 0;						\
166 		if (unlikely(get_desc >= start_thrs)) {			\
167 			netif_tx_start_queue(txq);			\
168 			_res = -1;					\
169 		}							\
170 		_res;							\
171 	})								\
172 
173 /**
174  * netif_txq_maybe_stop() - locklessly stop a Tx queue, if needed
175  * @txq:	struct netdev_queue to stop/start
176  * @get_desc:	get current number of free descriptors (see requirements below!)
177  * @stop_thrs:	minimal number of available descriptors for queue to be left
178  *		enabled
179  * @start_thrs:	minimal number of descriptors to re-enable the queue, can be
180  *		equal to @stop_thrs or higher to avoid frequent waking
181  *
182  * All arguments may be evaluated multiple times, beware of side effects.
183  * @get_desc must be a formula or a function call, it must always
184  * return up-to-date information when evaluated!
185  * Expected to be used from ndo_start_xmit, see the comment on top of the file.
186  *
187  * Returns:
188  *	 0 if the queue was stopped
189  *	 1 if the queue was left enabled
190  *	-1 if the queue was re-enabled (raced with waking)
191  */
192 #define netif_txq_maybe_stop(txq, get_desc, stop_thrs, start_thrs)	\
193 	({								\
194 		int _res;						\
195 									\
196 		_res = 1;						\
197 		if (unlikely(get_desc < stop_thrs))			\
198 			_res = netif_txq_try_stop(txq, get_desc, start_thrs); \
199 		_res;							\
200 	})								\
201 
202 /* Variant of netdev_tx_completed_queue() which guarantees smp_mb() if
203  * @bytes != 0, regardless of kernel config.
204  */
205 static inline void
206 netdev_txq_completed_mb(struct netdev_queue *dev_queue,
207 			unsigned int pkts, unsigned int bytes)
208 {
209 	if (IS_ENABLED(CONFIG_BQL))
210 		netdev_tx_completed_queue(dev_queue, pkts, bytes);
211 	else if (bytes)
212 		smp_mb();
213 }
214 
215 /**
216  * __netif_txq_completed_wake() - locklessly wake a Tx queue, if needed
217  * @txq:	struct netdev_queue to stop/start
218  * @pkts:	number of packets completed
219  * @bytes:	number of bytes completed
220  * @get_desc:	get current number of free descriptors (see requirements below!)
221  * @start_thrs:	minimal number of descriptors to re-enable the queue
222  * @down_cond:	down condition, predicate indicating that the queue should
223  *		not be woken up even if descriptors are available
224  *
225  * All arguments may be evaluated multiple times.
226  * @get_desc must be a formula or a function call, it must always
227  * return up-to-date information when evaluated!
228  * Reports completed pkts/bytes to BQL.
229  *
230  * Returns:
231  *	 0 if the queue was woken up
232  *	 1 if the queue was already enabled (or disabled but @down_cond is true)
233  *	-1 if the queue was left unchanged (@start_thrs not reached)
234  */
235 #define __netif_txq_completed_wake(txq, pkts, bytes,			\
236 				   get_desc, start_thrs, down_cond)	\
237 	({								\
238 		int _res;						\
239 									\
240 		/* Report to BQL and piggy back on its barrier.		\
241 		 * Barrier makes sure that anybody stopping the queue	\
242 		 * after this point sees the new consumer index.	\
243 		 * Pairs with barrier in netif_txq_try_stop().		\
244 		 */							\
245 		netdev_txq_completed_mb(txq, pkts, bytes);		\
246 									\
247 		_res = -1;						\
248 		if (pkts && likely(get_desc >= start_thrs)) {		\
249 			_res = 1;					\
250 			if (unlikely(netif_tx_queue_stopped(txq)) &&	\
251 			    !(down_cond)) {				\
252 				netif_tx_wake_queue(txq);		\
253 				_res = 0;				\
254 			}						\
255 		}							\
256 		_res;							\
257 	})
258 
259 #define netif_txq_completed_wake(txq, pkts, bytes, get_desc, start_thrs) \
260 	__netif_txq_completed_wake(txq, pkts, bytes, get_desc, start_thrs, false)
261 
262 /* subqueue variants follow */
263 
264 #define netif_subqueue_try_stop(dev, idx, get_desc, start_thrs)		\
265 	({								\
266 		struct netdev_queue *txq;				\
267 									\
268 		txq = netdev_get_tx_queue(dev, idx);			\
269 		netif_txq_try_stop(txq, get_desc, start_thrs);		\
270 	})
271 
272 #define netif_subqueue_maybe_stop(dev, idx, get_desc, stop_thrs, start_thrs) \
273 	({								\
274 		struct netdev_queue *txq;				\
275 									\
276 		txq = netdev_get_tx_queue(dev, idx);			\
277 		netif_txq_maybe_stop(txq, get_desc, stop_thrs, start_thrs); \
278 	})
279 
280 #define netif_subqueue_completed_wake(dev, idx, pkts, bytes,		\
281 				      get_desc, start_thrs)		\
282 	({								\
283 		struct netdev_queue *txq;				\
284 									\
285 		txq = netdev_get_tx_queue(dev, idx);			\
286 		netif_txq_completed_wake(txq, pkts, bytes,		\
287 					 get_desc, start_thrs);		\
288 	})
289 
290 #endif
291