xref: /dragonfly/share/man/man9/altq.9 (revision 6b5c5d0d) 
1.\"	$OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $
2.\"	$NetBSD: altq.9,v 1.14 2007/06/24 19:26:58 rumble Exp $
3.\"	$DragonFly: src/share/man/man9/altq.9,v 1.1 2007/11/18 14:10:41 swildner Exp $
4.\"
5.\" Copyright (C) 2001
6.\" Sony Computer Science Laboratories Inc.  All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.
16.\"
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
27.\" SUCH DAMAGE.
28.\"
29.Dd November 18, 2007
30.Dt ALTQ 9
31.Os
32.Sh NAME
33.Nm ALTQ
34.Nd kernel interfaces for manipulating output queues on network interfaces
35.Sh SYNOPSIS
36.In sys/types.h
37.In sys/socket.h
38.In net/if.h
39.In net/ifq_var.h
40.Ft static int
41.Fn ifq_enqueue "struct ifaltq *_ifq" "struct mbuf *_m" "struct altq_pkgattr *_pa"
42.Ft static int
43.Fn ifq_handoff "struct ifnet *_ifp" "struct mbuf *_m" "struct altq_pkgattr *_pa"
44.Ft struct mbuf *
45.Fn ifq_dequeue "struct ifaltq *_ifq" "struct mbuf *_mpolled"
46.Ft struct mbuf *
47.Fn ifq_poll "struct ifaltq *_ifq"
48.Ft void
49.Fn ifq_purge "struct ifaltq *_ifq"
50.Ft void
51.Fn ifq_classify "struct ifaltq *_ifq" "struct *mbuf _m" "uint8_t _af" "struct altq_pkgattr *_pa"
52.Ft int
53.Fn ifq_is_empty "struct ifaltq *_ifq"
54.Ft void
55.Fn ifq_set_maxlen "struct ifaltq *_ifq" "int _len"
56.Ft void
57.Fn ifq_set_ready "struct ifaltq *_ifq"
58.Ft int
59.Fn ifq_is_enabled "struct ifaltq *_ifq"
60.Sh DESCRIPTION
61The
62.Nm
63system is a framework to manage queueing disciplines on network
64interfaces.
65.Nm
66introduces new functions to manipulate output queues.
67The output queue functions are used to abstract queue operations and not to
68touch the internal fields of the output queue structure.
69.Pp
70.Fn ifq_enqueue
71and
72.Fn ifq_handoff
73enqueue a packet
74.Fa _m
75to the queue
76.Fa _ifq .
77The underlying queueing discipline may discard the packet.
78They return 0 on success, or
79.Er ENOBUFS
80if the packet is discarded.
81The packet pointed to by
82.Fa _m
83will be freed by the device driver on success or by the queueing discipline on
84failure, so that the caller should not touch
85.Fa _m
86after calling
87.Fn ifq_enqueue .
88.Fn ifq_handoff
89combines the enqueue operation with statistic generation and calls
90.Fn if_start
91upon successful enqueue to initiate the actual send.
92.Pp
93.Fn ifq_dequeue
94dequeues a packet from the queue.
95It returns the dequeued packet, or
96.Dv NULL
97if no packet is dequeued.
98The caller must always check the return value
99since a non-empty queue could return
100.Dv NULL
101under rate-limiting.
102.Pp
103.Fn ifq_poll
104returns the next packet without removing it from the queue.
105It is guaranteed by the underlying queueing discipline that
106.Fn ifq_dequeue
107immediately after
108.Fn ifq_poll
109returns the same packet.
110.Pp
111.Fn ifq_purge
112discards all the packets in the queue.
113The purge operation is needed since a non-work conserving queue cannot be
114emptied by a dequeue loop.
115.Pp
116.Fn ifq_classify
117classifies a packet to a scheduling class, and returns the result in
118.Fa _pa .
119.Pp
120.Fn ifq_is_empty
121can be used to check if the queue is empty.
122Note that
123.Fn ifq_dequeue
124could still return
125.Dv NULL
126if the queueing discipline is non-work conserving.
127.Pp
128.Fn ifq_set_maxlen
129sets the queue length limit to the default FIFO queue.
130.Pp
131.Fn ifq_set_ready
132sets a flag to indicate that this driver is converted to use the new macros.
133.Nm
134can be enabled only on interfaces with this flag.
135.Pp
136.Fn ifq_is_enabled
137returns 1 if
138.Nm
139is enabled for the queue, 0 if not.
140.Sh QUEUEING DISCIPLINES
141Queueing disciplines need to maintain
142.Fa ifq_len
143.Po
144used by
145.Fn ifq_is_empty
146.Pc .
147Queueing disciplines also need to guarantee that the same mbuf is returned if
148.Fn ifq_dequeue
149is called immediately after
150.Fn ifq_poll .
151.Sh SEE ALSO
152.Xr altq 4 ,
153.Xr pf 4 ,
154.Xr pf.conf 5 ,
155.Xr pfctl 8
156.Sh HISTORY
157The
158.Nm
159system first appeared in March 1997 and was imported into
160.Dx 1.1 .
161