1 .\" $NetBSD: altq.9,v 1.8 2002/05/28 11:41:45 wiz Exp $
2 .\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $
4 .\" Copyright (C) 2004 Max Laier. All rights reserved.
6 .\" Sony Computer Science Laboratories Inc. All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .Nd kernel interfaces for manipulating output queues on network interfaces
45 .Fn IFQ_ENQUEUE "struct ifaltq *ifq" "struct mbuf *m" "int error"
46 .Fn IFQ_HANDOFF "struct ifnet *ifp" "struct mbuf *m" "int error"
48 .Fa "struct ifnet *ifp" "struct mbuf *m" "int adjust" "int error"
52 .Fn IFQ_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m"
53 .Fn IFQ_POLL_NOLOCK "struct ifaltq *ifq" "struct mbuf *m"
54 .Fn IFQ_PURGE "struct ifaltq *ifq"
55 .Fn IFQ_IS_EMPTY "struct ifaltq *ifq"
57 .Ss Driver managed dequeue macros
58 .Fn IFQ_DRV_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m"
59 .Fn IFQ_DRV_PREPEND "struct ifaltq *ifq" "struct mbuf *m"
60 .Fn IFQ_DRV_PURGE "struct ifaltq *ifq"
61 .Fn IFQ_DRV_IS_EMPTY "struct ifaltq *ifq"
63 .Ss General setup macros
64 .Fn IFQ_SET_MAXLEN "struct ifaltq *ifq" "int len"
65 .Fn IFQ_INC_LEN "struct ifaltq *ifq"
66 .Fn IFQ_DEC_LEN "struct ifaltq *ifq"
67 .Fn IFQ_INC_DROPS "struct ifaltq *ifq"
68 .Fn IFQ_SET_READY "struct ifaltq *ifq"
72 system is a framework to manage queuing disciplines on network
75 introduces new macros to manipulate output queues.
76 The output queue macros are used to abstract queue operations and not to
77 touch the internal fields of the output queue structure.
78 The macros are independent from the
80 implementation, and compatible with the traditional
82 macros for ease of transition.
92 The underlying queuing discipline may discard the packet.
95 argument is set to 0 on success, or
97 if the packet is discarded.
98 The packet pointed to by
100 will be freed by the device driver on success, or by the queuing discipline on
101 failure, so the caller should not touch
107 combine the enqueue operation with statistic generation and call
109 upon successful enqueue to initiate the actual send.
112 dequeues a packet from the queue.
113 The dequeued packet is returned in
119 if no packet is dequeued.
120 The caller must always check
122 since a non-empty queue could return
127 returns the next packet without removing it from the queue.
128 The caller must hold the queue mutex when calling
130 in order to guarantee that a subsequent call to
131 .Fn IFQ_DEQUEUE_NOLOCK
132 dequeues the same packet.
135 variants (if available) always assume that the caller holds the queue mutex.
136 They can be grabbed with
142 discards all the packets in the queue.
143 The purge operation is needed since a non-work conserving queue cannot be
144 emptied by a dequeue loop.
147 can be used to check if the queue is empty.
152 if the queuing discipline is non-work conserving.
156 .Fa ifq->ifq_drv_maxlen
157 packets from the queue to the
159 queue and returns the first one via
166 even for a non-empty queue.
169 pass the packets from the
171 queue without obtaining the queue mutex.
172 It is the responsibility of the caller to protect against concurrent access.
175 for a given queue sets
186 Note that a driver must not mix
188 macros with the default dequeue macros as the default macros do not look at the
190 queue which might lead to an mbuf leak.
197 queue from where it will be obtained with the next call to
198 .Fn IFQ_DRV_DEQUEUE .
201 flushes all packets in the
208 checks for packets in the
211 If it is empty, it forwards to
215 sets the queue length limit to the default FIFO queue.
220 structure controls the length limit of the
227 increment or decrement the current queue length in packets.
228 This is mostly for internal purposes.
231 increments the drop counter and is identical to
233 It is defined for naming consistency only.
236 sets a flag to indicate that a driver was converted to use the new macros.
238 can be enabled only on interfaces with this flag.
240 .Ss Vt ifaltq structure
241 In order to keep compatibility with the existing code, the new
242 output queue structure
247 macros and the code directly referencing the fields within
252 ##old-style## ##new-style##
254 struct ifqueue { | struct ifaltq {
255 struct mbuf *ifq_head; | struct mbuf *ifq_head;
256 struct mbuf *ifq_tail; | struct mbuf *ifq_tail;
257 int ifq_len; | int ifq_len;
258 int ifq_maxlen; | int ifq_maxlen;
259 }; | /* driver queue fields */
261 | /* altq related fields */
266 The new structure replaces
271 ##old-style## ##new-style##
273 struct ifnet { | struct ifnet {
276 struct ifqueue if_snd; | struct ifaltq if_snd;
286 #define IFQ_DEQUEUE(ifq, m) \e
287 if (ALTQ_IS_ENABLED((ifq)) \e
288 ALTQ_DEQUEUE((ifq), (m)); \e
290 IF_DEQUEUE((ifq), (m));
292 .Ss Enqueue operation
293 The semantics of the enqueue operation is changed.
295 enqueue and packet drop are combined since they cannot be easily
296 separated in many queuing disciplines.
297 The new enqueue operation corresponds to the following macro that is
298 written with the old macros.
300 #define IFQ_ENQUEUE(ifq, m, error) \e
302 if (IF_QFULL((ifq))) { \e
304 (error) = ENOBUFS; \e
307 IF_ENQUEUE((ifq), (m)); \e
320 drop (and free) a packet if the enqueue operation fails.
323 If the enqueue operation fails,
329 mbuf is freed by the queuing discipline.
330 The caller should not touch mbuf after calling
332 so that the caller may need to copy
336 field beforehand for statistics.
340 can be used if only default interface statistics and an immediate call to
343 The caller should not use
345 since mbuf was already freed.
351 ##old-style## ##new-style##
354 ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0)
358 | mflags = m->m_flags;
359 | len = m->m_pkthdr.len;
360 s = splimp(); | s = splimp();
361 if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m,
363 IF_DROP(&ifp->if_snd); | if (error != 0) {
365 senderr(ENOBUFS); | return (error);
367 IF_ENQUEUE(&ifp->if_snd, m); |
368 ifp->if_obytes += | ifp->if_obytes += len;
370 if (m->m_flags & M_MCAST) | if (mflags & M_MCAST)
371 ifp->if_omcasts++; | ifp->if_omcasts++;
373 if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE)
375 (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp);
377 return (error); | return (error);
381 m_freem(m); | m_freem(m);
382 return (error); | return (error);
386 .Sh HOW TO CONVERT THE EXISTING DRIVERS
387 First, make sure the corresponding
389 is already converted to the new style.
394 Probably, you need to make changes to the lines that include
396 .Ss Empty check operation
399 to see whether the queue is empty or not, use
402 ##old-style## ##new-style##
404 if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_IS_EMPTY(&ifp->if_snd))
408 only checks if there is any packet stored in the queue.
416 if the queue is under rate-limiting.
417 .Ss Dequeue operation
422 Always check whether the dequeued mbuf is
432 due to rate-limiting.
434 ##old-style## ##new-style##
436 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m);
441 A driver is supposed to call
443 from transmission complete interrupts in order to trigger the next dequeue.
444 .Ss Poll-and-dequeue operation
445 If the code polls the packet at the head of the queue and actually uses
446 the packet before dequeuing it, use
449 .Fn IFQ_DEQUEUE_NOLOCK .
451 ##old-style## ##new-style##
453 | IFQ_LOCK(&ifp->if_snd);
454 m = ifp->if_snd.ifq_head; | IFQ_POLL_NOLOCK(&ifp->if_snd, m);
455 if (m != NULL) { | if (m != NULL) {
457 /* use m to get resources */ | /* use m to get resources */
458 if (something goes wrong) | if (something goes wrong)
459 | IFQ_UNLOCK(&ifp->if_snd);
462 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m);
463 | IFQ_UNLOCK(&ifp->if_snd);
465 /* kick the hardware */ | /* kick the hardware */
469 It is guaranteed that
470 .Fn IFQ_DEQUEUE_NOLOCK
471 under the same lock as a previous
473 returns the same packet.
474 Note that they need to be guarded by
476 .Ss Eliminating Fn IF_PREPEND
479 you have to eliminate it unless you can use a
481 queue which allows the use of
486 is to cancel the previous dequeue operation.
487 You have to convert the logic into poll-and-dequeue.
489 ##old-style## ##new-style##
491 | IFQ_LOCK(&ifp->if_snd);
492 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL_NOLOCK(&ifp->if_snd, m);
493 if (m != NULL) { | if (m != NULL) {
495 if (something_goes_wrong) { | if (something_goes_wrong) {
496 IF_PREPEND(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd);
500 | /* at this point, the driver
501 | * is committed to send this
504 | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m);
505 | IFQ_UNLOCK(&ifp->if_snd);
507 /* kick the hardware */ | /* kick the hardware */
515 Note that a non-work conserving queue cannot be emptied by a dequeue loop.
517 ##old-style## ##new-style##
519 while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd);
520 IF_DEQUEUE(&ifp->if_snd, m); |
525 .Ss Conversion using a driver managed queue
528 macros to their equivalent
534 ##old-style## ##new-style##
536 if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_DRV_IS_EMPTY(&ifp->if_snd))
539 Make sure that calls to
540 .Fn IFQ_DRV_DEQUEUE ,
544 are protected with a mutex of some kind.
554 with a sensible value if you plan to use the
559 to show this driver is converted to the new style.
560 (This is used to distinguish new-style drivers.)
562 ##old-style## ##new-style##
564 ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize);
565 | ifp->if_snd.ifq_drv_maxlen = qsize;
566 | IFQ_SET_READY(&ifp->if_snd);
567 if_attach(ifp); | if_attach(ifp);
571 The new macros for statistics:
573 ##old-style## ##new-style##
575 IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd);
577 ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd);
579 ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd);
582 .Sh QUEUING DISCIPLINES
583 Queuing disciplines need to maintain
587 Queuing disciplines also need to guarantee that the same mbuf is returned if
589 is called immediately after
598 system first appeared in March 1997 and found home in the KAME project
599 (http://www.kame.net).