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 Ss 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 int ifq_drops; | int ifq_drops;
260 }; | /* driver queue fields */
262 | /* altq related fields */
267 The new structure replaces
272 ##old-style## ##new-style##
274 struct ifnet { | struct ifnet {
277 struct ifqueue if_snd; | struct ifaltq if_snd;
287 #define IFQ_DEQUEUE(ifq, m) \e
288 if (ALTQ_IS_ENABLED((ifq)) \e
289 ALTQ_DEQUEUE((ifq), (m)); \e
291 IF_DEQUEUE((ifq), (m));
293 .Ss Enqueue operation
294 The semantics of the enqueue operation is changed.
296 enqueue and packet drop are combined since they cannot be easily
297 separated in many queuing disciplines.
298 The new enqueue operation corresponds to the following macro that is
299 written with the old macros.
301 #define IFQ_ENQUEUE(ifq, m, error) \e
303 if (IF_QFULL((ifq))) { \e
305 (error) = ENOBUFS; \e
308 IF_ENQUEUE((ifq), (m)); \e
321 drop (and free) a packet if the enqueue operation fails.
324 If the enqueue operation fails,
330 mbuf is freed by the queuing discipline.
331 The caller should not touch mbuf after calling
333 so that the caller may need to copy
337 field beforehand for statistics.
341 can be used if only default interface statistics and an immediate call to
344 The caller should not use
346 since mbuf was already freed.
352 ##old-style## ##new-style##
355 ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0)
359 | mflags = m->m_flags;
360 | len = m->m_pkthdr.len;
361 s = splimp(); | s = splimp();
362 if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m,
364 IF_DROP(&ifp->if_snd); | if (error != 0) {
366 senderr(ENOBUFS); | return (error);
368 IF_ENQUEUE(&ifp->if_snd, m); |
369 ifp->if_obytes += | ifp->if_obytes += len;
371 if (m->m_flags & M_MCAST) | if (mflags & M_MCAST)
372 ifp->if_omcasts++; | ifp->if_omcasts++;
374 if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE)
376 (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp);
378 return (error); | return (error);
382 m_freem(m); | m_freem(m);
383 return (error); | return (error);
387 .Sh HOW TO CONVERT THE EXISTING DRIVERS
388 First, make sure the corresponding
390 is already converted to the new style.
395 Probably, you need to make changes to the lines that include
397 .Ss Empty check operation
400 to see whether the queue is empty or not, use
403 ##old-style## ##new-style##
405 if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_IS_EMPTY(&ifp->if_snd))
409 only checks if there is any packet stored in the queue.
417 if the queue is under rate-limiting.
418 .Ss Dequeue operation
423 Always check whether the dequeued mbuf is
433 due to rate-limiting.
435 ##old-style## ##new-style##
437 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m);
442 A driver is supposed to call
444 from transmission complete interrupts in order to trigger the next dequeue.
445 .Ss Poll-and-dequeue operation
446 If the code polls the packet at the head of the queue and actually uses
447 the packet before dequeuing it, use
450 .Fn IFQ_DEQUEUE_NOLOCK .
452 ##old-style## ##new-style##
454 | IFQ_LOCK(&ifp->if_snd);
455 m = ifp->if_snd.ifq_head; | IFQ_POLL_NOLOCK(&ifp->if_snd, m);
456 if (m != NULL) { | if (m != NULL) {
458 /* use m to get resources */ | /* use m to get resources */
459 if (something goes wrong) | if (something goes wrong)
460 | IFQ_UNLOCK(&ifp->if_snd);
463 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m);
464 | IFQ_UNLOCK(&ifp->if_snd);
466 /* kick the hardware */ | /* kick the hardware */
470 It is guaranteed that
471 .Fn IFQ_DEQUEUE_NOLOCK
472 under the same lock as a previous
474 returns the same packet.
475 Note that they need to be guarded by
477 .Ss Eliminating Fn IF_PREPEND
480 you have to eliminate it unless you can use a
482 queue which allows the use of
487 is to cancel the previous dequeue operation.
488 You have to convert the logic into poll-and-dequeue.
490 ##old-style## ##new-style##
492 | IFQ_LOCK(&ifp->if_snd);
493 IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL_NOLOCK(&ifp->if_snd, m);
494 if (m != NULL) { | if (m != NULL) {
496 if (something_goes_wrong) { | if (something_goes_wrong) {
497 IF_PREPEND(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd);
501 | /* at this point, the driver
502 | * is committed to send this
505 | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m);
506 | IFQ_UNLOCK(&ifp->if_snd);
508 /* kick the hardware */ | /* kick the hardware */
516 Note that a non-work conserving queue cannot be emptied by a dequeue loop.
518 ##old-style## ##new-style##
520 while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd);
521 IF_DEQUEUE(&ifp->if_snd, m); |
526 .Ss Conversion using a driver managed queue
529 macros to their equivalent
535 ##old-style## ##new-style##
537 if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_DRV_IS_EMPTY(&ifp->if_snd))
540 Make sure that calls to
541 .Fn IFQ_DRV_DEQUEUE ,
545 are protected with a mutex of some kind.
555 with a sensible value if you plan to use the
560 to show this driver is converted to the new style.
561 (This is used to distinguish new-style drivers.)
563 ##old-style## ##new-style##
565 ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize);
566 | ifp->if_snd.ifq_drv_maxlen = qsize;
567 | IFQ_SET_READY(&ifp->if_snd);
568 if_attach(ifp); | if_attach(ifp);
572 The new macros for statistics:
574 ##old-style## ##new-style##
576 IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd);
578 ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd);
580 ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd);
583 .Sh QUEUING DISCIPLINES
584 Queuing disciplines need to maintain
588 Queuing disciplines also need to guarantee that the same mbuf is returned if
590 is called immediately after
599 system first appeared in March 1997.