2 * Copyright (c) 1998-2010 Luigi Rizzo, Universita` di Pisa
3 * Portions Copyright (c) 2000 Akamba Corp.
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 #ifndef _IP_DUMMYNET_H
31 #define _IP_DUMMYNET_H
34 * Definition of the kernel-userland API for dummynet.
36 * Setsockopt() and getsockopt() pass a batch of objects, each
37 * of them starting with a "struct dn_id" which should fully identify
38 * the object and its relation with others in the sequence.
39 * The first object in each request should have
40 * type= DN_CMD_*, id = DN_API_VERSION.
41 * For other objects, type and subtype specify the object, len indicates
42 * the total length including the header, and 'id' identifies the specific
45 * Most objects are numbered with an identifier in the range 1..65535.
46 * DN_MAX_ID indicates the first value outside the range.
49 #define DN_API_VERSION 12500000
50 #define DN_MAX_ID 0x10000
53 uint16_t len; /* total obj len including this header */
56 uint32_t id; /* generic id */
60 * These values are in the type field of struct dn_id.
61 * To preserve the ABI, never rearrange the list or delete
62 * entries with the exception of DN_LAST
73 DN_FLOW, /* struct dn_flow */
74 DN_TEXT, /* opaque text is the object */
76 DN_CMD_CONFIG = 0x80, /* objects follow */
77 DN_CMD_DELETE, /* subtype + list of entries */
78 DN_CMD_GET, /* subtype + list of entries */
80 /* for compatibility with FreeBSD 7.2/8 */
85 /* special commands for emulation of sysctl variables */
89 /* subtypes used for setting/getting extra parameters.
90 * these subtypes used with IP_DUMMYNET3 command (get)
91 * and DN_TEXT (set). */
92 DN_AQM_PARAMS, /* AQM extra params */
93 DN_SCH_PARAMS, /* scheduler extra params */
98 enum { /* subtype for schedulers, flowset and the like */
102 /* others are in individual modules */
105 enum { /* user flags */
106 DN_HAVE_MASK = 0x0001, /* fs or sched has a mask */
107 DN_NOERROR = 0x0002, /* do not report errors */
108 DN_QHT_HASH = 0x0004, /* qht is a hash table */
109 DN_QSIZE_BYTES = 0x0008, /* queue size is in bytes */
110 DN_HAS_PROFILE = 0x0010, /* a link has a profile */
112 DN_IS_GENTLE_RED= 0x0040,
115 DN_IS_AQM = 0x0100, /* AQMs: e.g Codel & PIE */
117 DN_PIPE_CMD = 0x1000, /* pipe config... */
127 * Userland sets bw and delay in bits/s and milliseconds.
128 * The kernel converts this back and forth to bits/tick and ticks.
129 * XXX what about burst ?
132 int bandwidth; /* bit/s or bits/tick. */
133 int delay; /* ms and ticks */
134 uint64_t burst; /* scaled. bits*Hz XXX */
138 * A flowset, which is a template for flows. Contains parameters
139 * from the command line: id, target scheduler, queue sizes, plr,
140 * flow masks, buckets for the flow hash, and possibly scheduler-
141 * specific parameters (weight, quantum and so on).
145 uint32_t fs_nr; /* the flowset number */
146 uint32_t flags; /* userland flags */
147 int qsize; /* queue size in slots or bytes */
148 int32_t plr; /* PLR, pkt loss rate (2^31-1 means 100%) */
149 uint32_t buckets; /* buckets used for the queue hash table */
151 struct ipfw_flow_id flow_mask;
152 uint32_t sched_nr; /* the scheduler we attach to */
153 /* generic scheduler parameters. Leave them at -1 if unset.
154 * Now we use 0: weight, 1: lmax, 2: priority
158 /* RED/GRED parameters.
159 * weight and probabilities are in the range 0..1 represented
160 * in fixed point arithmetic with SCALE_RED decimal bits.
163 #define SCALE(x) ( (x) << SCALE_RED )
164 #define SCALE_VAL(x) ( (x) >> SCALE_RED )
165 #define SCALE_MUL(x,y) ( ( (x) * (y) ) >> SCALE_RED )
166 int w_q ; /* queue weight (scaled) */
167 int max_th ; /* maximum threshold for queue (scaled) */
168 int min_th ; /* minimum threshold for queue (scaled) */
169 int max_p ; /* maximum value for p_b (scaled) */
174 * dn_flow collects flow_id and stats for queues and scheduler
175 * instances, and is used to pass these info to userland.
176 * oid.type/oid.subtype describe the object, oid.id is number
177 * of the parent object.
181 struct ipfw_flow_id fid;
182 uint64_t tot_pkts; /* statistics counters */
184 uint32_t length; /* Queue length, in packets */
185 uint32_t len_bytes; /* Queue length, in bytes */
191 * Scheduler template, mostly indicating the name, number,
192 * sched_mask and buckets.
196 uint32_t sched_nr; /* N, scheduler number */
197 uint32_t buckets; /* number of buckets for the instances */
198 uint32_t flags; /* have_mask, ... */
200 char name[16]; /* null terminated */
201 /* mask to select the appropriate scheduler instance */
202 struct ipfw_flow_id sched_mask; /* M */
206 /* A delay profile is attached to a link.
207 * Note that a profile, as any other object, cannot be longer than 2^16
209 #define ED_MAX_SAMPLES_NO 1024
212 /* fields to simulate a delay profile */
213 #define ED_MAX_NAME_LEN 32
214 char name[ED_MAX_NAME_LEN];
217 int bandwidth; // XXX use link bandwidth?
218 int samples_no; /* actual len of samples[] */
219 int samples[ED_MAX_SAMPLES_NO]; /* may be shorter */
223 /* Extra parameters for AQM and scheduler.
224 * This struct is used to pass and retrieve parameters (configurations)
225 * to/from AQM and Scheduler.
227 struct dn_extra_parms {
231 #define DN_MAX_EXTRA_PARM 10
232 int64_t par[DN_MAX_EXTRA_PARM];
237 * Overall structure of dummynet
239 In dummynet, packets are selected with the firewall rules, and passed
240 to two different objects: PIPE or QUEUE (bad name).
242 A QUEUE defines a classifier, which groups packets into flows
243 according to a 'mask', puts them into independent queues (one
244 per flow) with configurable size and queue management policy,
245 and passes flows to a scheduler:
247 (flow_mask|sched_mask) sched_mask
248 +---------+ weight Wx +-------------+
249 | |->-[flow]-->--| |-+
250 -->--| QUEUE x | ... | | |
251 | |->-[flow]-->--| SCHEDuler N | |
253 ... | +--[LINK N]-->--
254 +---------+ weight Wy | | +--[LINK N]-->--
255 | |->-[flow]-->--| | |
256 -->--| QUEUE y | ... | | |
257 | |->-[flow]-->--| | |
258 +---------+ +-------------+ |
261 Many QUEUE objects can connect to the same scheduler, each
262 QUEUE object can have its own set of parameters.
264 In turn, the SCHEDuler 'forks' multiple instances according
265 to a 'sched_mask', each instance manages its own set of queues
266 and transmits on a private instance of a configurable LINK.
268 A PIPE is a simplified version of the above, where there
269 is no flow_mask, and each scheduler instance handles a single queue.
271 The following data structures (visible from userland) describe
272 the objects used by dummynet:
274 + dn_link, contains the main configuration parameters related
275 to delay and bandwidth;
276 + dn_profile describes a delay profile;
277 + dn_flow describes the flow status (flow id, statistics)
279 + dn_sch describes a scheduler
280 + dn_fs describes a flowset (msk, weight, queue parameters)
285 #endif /* _IP_DUMMYNET_H */