1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3 * 4 * Copyright (c) 1998-2010 Luigi Rizzo, Universita` di Pisa 5 * Portions Copyright (c) 2000 Akamba Corp. 6 * 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 THE AUTHOR 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 THE AUTHOR 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 * $FreeBSD$ 30 */ 31 32 #ifndef _IP_DUMMYNET_H 33 #define _IP_DUMMYNET_H 34 #define NEW_AQM 35 /* 36 * Definition of the kernel-userland API for dummynet. 37 * 38 * Setsockopt() and getsockopt() pass a batch of objects, each 39 * of them starting with a "struct dn_id" which should fully identify 40 * the object and its relation with others in the sequence. 41 * The first object in each request should have 42 * type= DN_CMD_*, id = DN_API_VERSION. 43 * For other objects, type and subtype specify the object, len indicates 44 * the total length including the header, and 'id' identifies the specific 45 * object. 46 * 47 * Most objects are numbered with an identifier in the range 1..65535. 48 * DN_MAX_ID indicates the first value outside the range. 49 */ 50 51 #define DN_API_VERSION 12500000 52 #define DN_MAX_ID 0x10000 53 54 struct dn_id { 55 uint16_t len; /* total obj len including this header */ 56 uint8_t type; 57 uint8_t subtype; 58 uint32_t id; /* generic id */ 59 }; 60 61 /* 62 * These values are in the type field of struct dn_id. 63 * To preserve the ABI, never rearrange the list or delete 64 * entries with the exception of DN_LAST 65 */ 66 enum { 67 DN_NONE = 0, 68 DN_LINK = 1, 69 DN_FS, 70 DN_SCH, 71 DN_SCH_I, 72 DN_QUEUE, 73 DN_DELAY_LINE, 74 DN_PROFILE, 75 DN_FLOW, /* struct dn_flow */ 76 DN_TEXT, /* opaque text is the object */ 77 78 DN_CMD_CONFIG = 0x80, /* objects follow */ 79 DN_CMD_DELETE, /* subtype + list of entries */ 80 DN_CMD_GET, /* subtype + list of entries */ 81 DN_CMD_FLUSH, 82 /* for compatibility with FreeBSD 7.2/8 */ 83 DN_COMPAT_PIPE, 84 DN_COMPAT_QUEUE, 85 DN_GET_COMPAT, 86 87 /* special commands for emulation of sysctl variables */ 88 DN_SYSCTL_GET, 89 DN_SYSCTL_SET, 90 #ifdef NEW_AQM 91 /* subtypes used for setting/getting extra parameters. 92 * these subtypes used with IP_DUMMYNET3 command (get) 93 * and DN_TEXT (set). */ 94 DN_AQM_PARAMS, /* AQM extra params */ 95 DN_SCH_PARAMS, /* scheduler extra params */ 96 #endif 97 DN_LAST, 98 }; 99 100 enum { /* subtype for schedulers, flowset and the like */ 101 DN_SCHED_UNKNOWN = 0, 102 DN_SCHED_FIFO = 1, 103 DN_SCHED_WF2QP = 2, 104 /* others are in individual modules */ 105 }; 106 107 enum { /* user flags */ 108 DN_HAVE_MASK = 0x0001, /* fs or sched has a mask */ 109 DN_NOERROR = 0x0002, /* do not report errors */ 110 DN_QHT_HASH = 0x0004, /* qht is a hash table */ 111 DN_QSIZE_BYTES = 0x0008, /* queue size is in bytes */ 112 DN_HAS_PROFILE = 0x0010, /* a link has a profile */ 113 DN_IS_RED = 0x0020, 114 DN_IS_GENTLE_RED= 0x0040, 115 DN_IS_ECN = 0x0080, 116 #ifdef NEW_AQM 117 DN_IS_AQM = 0x0100, /* AQMs: e.g Codel & PIE */ 118 #endif 119 DN_PIPE_CMD = 0x1000, /* pipe config... */ 120 }; 121 122 /* 123 * link template. 124 */ 125 struct dn_link { 126 struct dn_id oid; 127 128 /* 129 * Userland sets bw and delay in bits/s and milliseconds. 130 * The kernel converts this back and forth to bits/tick and ticks. 131 * XXX what about burst ? 132 */ 133 int32_t link_nr; 134 uint32_t bandwidth; /* bit/s or bits/tick. */ 135 int delay; /* ms and ticks */ 136 uint64_t burst; /* scaled. bits*Hz XXX */ 137 }; 138 139 /* 140 * A flowset, which is a template for flows. Contains parameters 141 * from the command line: id, target scheduler, queue sizes, plr, 142 * flow masks, buckets for the flow hash, and possibly scheduler- 143 * specific parameters (weight, quantum and so on). 144 */ 145 struct dn_fs { 146 struct dn_id oid; 147 uint32_t fs_nr; /* the flowset number */ 148 uint32_t flags; /* userland flags */ 149 int qsize; /* queue size in slots or bytes */ 150 int32_t plr; /* PLR, pkt loss rate (2^31-1 means 100%) */ 151 uint32_t buckets; /* buckets used for the queue hash table */ 152 153 struct ipfw_flow_id flow_mask; 154 uint32_t sched_nr; /* the scheduler we attach to */ 155 /* generic scheduler parameters. Leave them at -1 if unset. 156 * Now we use 0: weight, 1: lmax, 2: priority 157 */ 158 int par[4]; 159 160 /* RED/GRED parameters. 161 * weight and probabilities are in the range 0..1 represented 162 * in fixed point arithmetic with SCALE_RED decimal bits. 163 */ 164 #define SCALE_RED 16 165 #define SCALE(x) ( (x) << SCALE_RED ) 166 #define SCALE_VAL(x) ( (x) >> SCALE_RED ) 167 #define SCALE_MUL(x,y) ( ( (x) * (y) ) >> SCALE_RED ) 168 int w_q ; /* queue weight (scaled) */ 169 int max_th ; /* maximum threshold for queue (scaled) */ 170 int min_th ; /* minimum threshold for queue (scaled) */ 171 int max_p ; /* maximum value for p_b (scaled) */ 172 173 }; 174 175 /* 176 * dn_flow collects flow_id and stats for queues and scheduler 177 * instances, and is used to pass these info to userland. 178 * oid.type/oid.subtype describe the object, oid.id is number 179 * of the parent object. 180 */ 181 struct dn_flow { 182 struct dn_id oid; 183 struct ipfw_flow_id fid; 184 uint64_t tot_pkts; /* statistics counters */ 185 uint64_t tot_bytes; 186 uint32_t length; /* Queue length, in packets */ 187 uint32_t len_bytes; /* Queue length, in bytes */ 188 uint32_t drops; 189 }; 190 191 /* 192 * Scheduler template, mostly indicating the name, number, 193 * sched_mask and buckets. 194 */ 195 struct dn_sch { 196 struct dn_id oid; 197 uint32_t sched_nr; /* N, scheduler number */ 198 uint32_t buckets; /* number of buckets for the instances */ 199 uint32_t flags; /* have_mask, ... */ 200 201 char name[16]; /* null terminated */ 202 /* mask to select the appropriate scheduler instance */ 203 struct ipfw_flow_id sched_mask; /* M */ 204 }; 205 206 /* A delay profile is attached to a link. 207 * Note that a profile, as any other object, cannot be longer than 2^16 208 */ 209 #define ED_MAX_SAMPLES_NO 1024 210 struct dn_profile { 211 struct dn_id oid; 212 /* fields to simulate a delay profile */ 213 #define ED_MAX_NAME_LEN 32 214 char name[ED_MAX_NAME_LEN]; 215 int link_nr; 216 int loss_level; 217 uint32_t bandwidth; // XXX use link bandwidth? 218 int samples_no; /* actual len of samples[] */ 219 int samples[ED_MAX_SAMPLES_NO]; /* may be shorter */ 220 }; 221 222 #ifdef NEW_AQM 223 /* Extra parameters for AQM and scheduler. 224 * This struct is used to pass and retrieve parameters (configurations) 225 * to/from AQM and Scheduler. 226 */ 227 struct dn_extra_parms { 228 struct dn_id oid; 229 char name[16]; 230 uint32_t nr; 231 #define DN_MAX_EXTRA_PARM 10 232 int64_t par[DN_MAX_EXTRA_PARM]; 233 }; 234 #endif 235 236 /* 237 * Overall structure of dummynet 238 239 In dummynet, packets are selected with the firewall rules, and passed 240 to two different objects: PIPE or QUEUE (bad name). 241 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: 246 247 (flow_mask|sched_mask) sched_mask 248 +---------+ weight Wx +-------------+ 249 | |->-[flow]-->--| |-+ 250 -->--| QUEUE x | ... | | | 251 | |->-[flow]-->--| SCHEDuler N | | 252 +---------+ | | | 253 ... | +--[LINK N]-->-- 254 +---------+ weight Wy | | +--[LINK N]-->-- 255 | |->-[flow]-->--| | | 256 -->--| QUEUE y | ... | | | 257 | |->-[flow]-->--| | | 258 +---------+ +-------------+ | 259 +-------------+ 260 261 Many QUEUE objects can connect to the same scheduler, each 262 QUEUE object can have its own set of parameters. 263 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. 267 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. 270 271 The following data structures (visible from userland) describe 272 the objects used by dummynet: 273 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) 278 279 + dn_sch describes a scheduler 280 + dn_fs describes a flowset (msk, weight, queue parameters) 281 282 * 283 */ 284 285 #endif /* _IP_DUMMYNET_H */ 286