Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 19 | */ |
| 20 | #ifndef __PJ_SOCK_QOS_H__ |
| 21 | #define __PJ_SOCK_QOS_H__ |
| 22 | |
| 23 | /** |
| 24 | * @file sock_qos.h |
| 25 | * @brief Socket QoS API |
| 26 | */ |
| 27 | |
| 28 | #include <pj/sock.h> |
| 29 | |
| 30 | PJ_BEGIN_DECL |
| 31 | |
| 32 | |
| 33 | /** |
| 34 | * @defgroup socket_qos Socket Quality of Service (QoS) API: TOS, DSCP, WMM, IEEE 802.1p |
| 35 | * @ingroup PJ_SOCK |
| 36 | * @{ |
| 37 | |
| 38 | |
| 39 | \section intro QoS Technologies |
| 40 | |
| 41 | QoS settings are available for both Layer 2 and 3 of TCP/IP protocols: |
| 42 | |
| 43 | \subsection intro_ieee8021p Layer 2: IEEE 802.1p for Ethernet |
| 44 | |
| 45 | IEEE 802.1p tagging will mark frames sent by a host for prioritized |
| 46 | delivery using a 3-bit Priority field in the virtual local area network |
| 47 | (VLAN) header of the Ethernet frame. The VLAN header is placed inside |
| 48 | the Ethernet header, between the Source Address field and either the |
| 49 | Length field (for an IEEE 802.3 frame) or the EtherType field (for an |
| 50 | Ethernet II frame). |
| 51 | |
| 52 | \subsection intro_wmm Layer 2: WMM |
| 53 | |
| 54 | At the Network Interface layer for IEEE 802.11 wireless, the Wi-Fi |
| 55 | Alliance certification for Wi-Fi Multimedia (WMM) defines four access |
| 56 | categories for prioritizing network traffic. These access categories |
| 57 | are (in order of highest to lowest priority) voice, video, best-effort, |
| 58 | and background. Host support for WMM prioritization requires that both |
| 59 | wireless network adapters and their drivers support WMM. Wireless |
| 60 | access points (APs) must have WMM enabled. |
| 61 | |
| 62 | \subsection intro_dscp Layer 3: DSCP |
| 63 | |
| 64 | At the Internet layer, you can use Differentiated Services/Diffserv and |
| 65 | set the value of the Differentiated Services Code Point (DSCP) in the |
| 66 | IP header. As defined in RFC 2474, the DSCP value is the high-order 6 bits |
| 67 | of the IP version 4 (IPv4) TOS field and the IP version 6 (IPv6) Traffic |
| 68 | Class field. |
| 69 | |
| 70 | \subsection intro_other Layer 3: Other |
| 71 | |
| 72 | Other mechanisms exist (such as RSVP, IntServ) but this will not be |
| 73 | implemented. |
| 74 | |
| 75 | |
| 76 | \section availability QoS Availability |
| 77 | |
| 78 | \subsection linux Linux |
| 79 | |
| 80 | DSCP is available via IP TOS option. |
| 81 | |
| 82 | Ethernet 802.1p tagging is done by setting setsockopt(SO_PRIORITY) option |
| 83 | of the socket, then with the set_egress_map option of the vconfig utility |
| 84 | to convert this to set vlan-qos field of the packet. |
| 85 | |
| 86 | WMM is not known to be available. |
| 87 | |
| 88 | \subsection windows Windows and Windows Mobile |
| 89 | |
| 90 | (It's a mess!) |
| 91 | |
| 92 | DSCP is settable with setsockopt() on Windows 2000 or older, but Windows |
| 93 | would silently ignore this call on WinXP or later, unless administrator |
| 94 | modifies the registry. On Windows 2000, Windows XP, and Windows Server |
| 95 | 2003, GQoS (Generic QoS) API is the standard API, but this API may not be |
| 96 | supported in the future. On Vista and Windows 7, the is a new QoS2 API, |
| 97 | also known as Quality Windows Audio-Video Experience (qWAVE). |
| 98 | |
| 99 | IEEE 802.1p tagging is available via Traffic Control (TC) API, available |
| 100 | on Windows XP SP2, but this needs administrator access. For Vista and |
| 101 | later, it's in qWAVE. |
| 102 | |
| 103 | WMM is available for mobile platforms on Windows Mobile 6 platform and |
| 104 | Windows Embedded CE 6, via setsockopt(IP_DSCP_TRAFFIC_TYPE). qWAVE |
| 105 | supports this as well. |
| 106 | |
| 107 | \subsection symbian Symbian S60 3rd Ed |
| 108 | |
| 109 | Both DSCP and WMM is supported via RSocket::SetOpt() with will set both |
| 110 | Layer 2 and Layer 3 QoS settings accordingly. Internally, PJLIB sets the |
| 111 | DSCP field of the socket, and based on certain DSCP values mapping, |
| 112 | Symbian will set the WMM tag accordingly. |
| 113 | |
| 114 | \section api PJLIB's QoS API Abstraction |
| 115 | |
| 116 | Based on the above, the following API is implemented. |
| 117 | |
| 118 | Declare the following "standard" traffic types. |
| 119 | |
| 120 | \code |
| 121 | typedef enum pj_qos_type |
| 122 | { |
| 123 | PJ_QOS_TYPE_BEST_EFFORT, |
| 124 | PJ_QOS_TYPE_BACKGROUND, |
| 125 | PJ_QOS_TYPE_VIDEO, |
| 126 | PJ_QOS_TYPE_VOICE, |
| 127 | PJ_QOS_TYPE_CONTROL |
| 128 | } pj_qos_type; |
| 129 | \endcode |
| 130 | |
| 131 | The traffic classes above will determine how the Layer 2 and 3 QoS |
| 132 | settings will be used. The standard mapping between the classes above |
| 133 | to the corresponding Layer 2 and 3 settings are as follows: |
| 134 | |
| 135 | \code |
| 136 | ================================================================= |
| 137 | PJLIB Traffic Type IP DSCP WMM 802.1p |
| 138 | ----------------------------------------------------------------- |
| 139 | BEST_EFFORT 0x00 BE (Bulk Effort) 0 |
| 140 | BACKGROUND 0x08 BK (Bulk) 2 |
| 141 | VIDEO 0x28 VI (Video) 5 |
| 142 | VOICE 0x30 VO (Voice) 6 |
| 143 | CONTROL 0x38 VO (Voice) 7 |
| 144 | ================================================================= |
| 145 | \endcode |
| 146 | |
| 147 | There are two sets of API provided to manipulate the QoS parameters. |
| 148 | |
| 149 | \subsection portable_api Portable API |
| 150 | |
| 151 | The first set of API is: |
| 152 | |
| 153 | \code |
| 154 | // Set QoS parameters |
| 155 | PJ_DECL(pj_status_t) pj_sock_set_qos_type(pj_sock_t sock, |
| 156 | pj_qos_type val); |
| 157 | |
| 158 | // Get QoS parameters |
| 159 | PJ_DECL(pj_status_t) pj_sock_get_qos_type(pj_sock_t sock, |
| 160 | pj_qos_type *p_val); |
| 161 | \endcode |
| 162 | |
| 163 | The API will set the traffic type according to the DSCP class, for both |
| 164 | Layer 2 and Layer 3 QoS settings, where it's available. If any of the |
| 165 | layer QoS setting is not settable, the API will silently ignore it. |
| 166 | If both layers are not setable, the API will return error. |
| 167 | |
| 168 | The API above is the recommended use of QoS, since it is the most |
| 169 | portable across all platforms. |
| 170 | |
| 171 | \subsection detail_api Fine Grained Control API |
| 172 | |
| 173 | The second set of API is intended for application that wants to fine |
| 174 | tune the QoS parameters. |
| 175 | |
| 176 | The Layer 2 and 3 QoS parameters are stored in pj_qos_params structure: |
| 177 | |
| 178 | \code |
| 179 | typedef enum pj_qos_flag |
| 180 | { |
| 181 | PJ_QOS_PARAM_HAS_DSCP = 1, |
| 182 | PJ_QOS_PARAM_HAS_SO_PRIO = 2, |
| 183 | PJ_QOS_PARAM_HAS_WMM = 4 |
| 184 | } pj_qos_flag; |
| 185 | |
| 186 | typedef enum pj_qos_wmm_prio |
| 187 | { |
| 188 | PJ_QOS_WMM_PRIO_BULK_EFFORT, |
| 189 | PJ_QOS_WMM_PRIO_BULK, |
| 190 | PJ_QOS_WMM_PRIO_VIDEO, |
| 191 | PJ_QOS_WMM_PRIO_VOICE |
| 192 | } pj_qos_wmm_prio; |
| 193 | |
| 194 | typedef struct pj_qos_params |
| 195 | { |
| 196 | pj_uint8_t flags; // Determines which values to |
| 197 | // set, bitmask of pj_qos_flag |
| 198 | pj_uint8_t dscp_val; // The 6 bits DSCP value to set |
| 199 | pj_uint8_t so_prio; // SO_PRIORITY value |
| 200 | pj_qos_wmm_prio wmm_prio; // WMM priority value |
| 201 | } pj_qos_params; |
| 202 | \endcode |
| 203 | |
| 204 | The second set of API with more fine-grained control over the parameters |
| 205 | are: |
| 206 | |
| 207 | \code |
| 208 | // Retrieve QoS params for the specified traffic type |
| 209 | PJ_DECL(pj_status_t) pj_qos_get_params(pj_qos_type type, |
| 210 | pj_qos_params *p); |
| 211 | |
| 212 | // Set QoS parameters to the socket |
| 213 | PJ_DECL(pj_status_t) pj_sock_set_qos_params(pj_sock_t sock, |
| 214 | const pj_qos_params *p); |
| 215 | |
| 216 | // Get QoS parameters from the socket |
| 217 | PJ_DECL(pj_status_t) pj_sock_get_qos_params(pj_sock_t sock, |
| 218 | pj_qos_params *p); |
| 219 | \endcode |
| 220 | |
| 221 | |
| 222 | Important: |
| 223 | |
| 224 | The pj_sock_set/get_qos_params() APIs are not portable, and it's probably |
| 225 | only going to be implemented on Linux. Application should always try to |
| 226 | use pj_sock_set_qos_type() instead. |
| 227 | */ |
| 228 | |
| 229 | |
| 230 | /** |
| 231 | * High level traffic classification. |
| 232 | */ |
| 233 | typedef enum pj_qos_type |
| 234 | { |
| 235 | PJ_QOS_TYPE_BEST_EFFORT, /**< Best effort traffic (default value). |
| 236 | Any QoS function calls with specifying |
| 237 | this value are effectively no-op */ |
| 238 | PJ_QOS_TYPE_BACKGROUND, /**< Background traffic. */ |
| 239 | PJ_QOS_TYPE_VIDEO, /**< Video traffic. */ |
| 240 | PJ_QOS_TYPE_VOICE, /**< Voice traffic. */ |
| 241 | PJ_QOS_TYPE_CONTROL /**< Control traffic. */ |
| 242 | } pj_qos_type; |
| 243 | |
| 244 | /** |
| 245 | * Bitmask flag to indicate which QoS layer setting is set in the |
| 246 | * \a flags field of the #pj_qos_params structure. |
| 247 | */ |
| 248 | typedef enum pj_qos_flag |
| 249 | { |
| 250 | PJ_QOS_PARAM_HAS_DSCP = 1, /**< DSCP field is set. */ |
| 251 | PJ_QOS_PARAM_HAS_SO_PRIO = 2, /**< Socket SO_PRIORITY */ |
| 252 | PJ_QOS_PARAM_HAS_WMM = 4 /**< WMM field is set. */ |
| 253 | } pj_qos_flag; |
| 254 | |
| 255 | |
| 256 | /** |
| 257 | * Standard WMM priorities. |
| 258 | */ |
| 259 | typedef enum pj_qos_wmm_prio |
| 260 | { |
| 261 | PJ_QOS_WMM_PRIO_BULK_EFFORT, /**< Bulk effort priority */ |
| 262 | PJ_QOS_WMM_PRIO_BULK, /**< Bulk priority. */ |
| 263 | PJ_QOS_WMM_PRIO_VIDEO, /**< Video priority */ |
| 264 | PJ_QOS_WMM_PRIO_VOICE /**< Voice priority */ |
| 265 | } pj_qos_wmm_prio; |
| 266 | |
| 267 | |
| 268 | /** |
| 269 | * QoS parameters to be set or retrieved to/from the socket. |
| 270 | */ |
| 271 | typedef struct pj_qos_params |
| 272 | { |
| 273 | pj_uint8_t flags; /**< Determines which values to |
| 274 | set, bitmask of pj_qos_flag */ |
| 275 | pj_uint8_t dscp_val; /**< The 6 bits DSCP value to set */ |
| 276 | pj_uint8_t so_prio; /**< SO_PRIORITY value */ |
| 277 | pj_qos_wmm_prio wmm_prio; /**< WMM priority value */ |
| 278 | } pj_qos_params; |
| 279 | |
| 280 | |
| 281 | |
| 282 | /** |
| 283 | * This is the high level and portable API to enable QoS on the specified |
| 284 | * socket, by setting the traffic type to the specified parameter. |
| 285 | * |
| 286 | * @param sock The socket. |
| 287 | * @param type Traffic type to be set. |
| 288 | * |
| 289 | * @return PJ_SUCCESS if at least Layer 2 or Layer 3 setting is |
| 290 | * successfully set. If both Layer 2 and Layer 3 settings |
| 291 | * can't be set, this function will return error. |
| 292 | */ |
| 293 | PJ_DECL(pj_status_t) pj_sock_set_qos_type(pj_sock_t sock, |
| 294 | pj_qos_type type); |
| 295 | |
| 296 | /** |
| 297 | * This is the high level and portable API to get the traffic type that has |
| 298 | * been set on the socket. On occasions where the Layer 2 or Layer 3 settings |
| 299 | * were modified by using low level API, this function may return approximation |
| 300 | * of the closest QoS type that matches the settings. |
| 301 | * |
| 302 | * @param sock The socket. |
| 303 | * @param p_type Pointer to receive the traffic type of the socket. |
| 304 | * |
| 305 | * @return PJ_SUCCESS if traffic type for the socket can be obtained |
| 306 | * or approximated.. |
| 307 | */ |
| 308 | PJ_DECL(pj_status_t) pj_sock_get_qos_type(pj_sock_t sock, |
| 309 | pj_qos_type *p_type); |
| 310 | |
| 311 | |
| 312 | /** |
| 313 | * This is a convenience function to apply QoS to the socket, and print error |
| 314 | * logging if the operations failed. Both QoS traffic type and the low level |
| 315 | * QoS parameters can be applied with this function. |
| 316 | * |
| 317 | * @param sock The socket handle. |
| 318 | * @param qos_type QoS traffic type. The QoS traffic type will be applied |
| 319 | * only if the value is not PJ_QOS_TYPE_BEST_EFFORT, |
| 320 | * @param qos_params Optional low-level QoS parameters. This will be |
| 321 | * applied only if this argument is not NULL and the |
| 322 | * flags inside the structure is non-zero. Upon return, |
| 323 | * the flags will indicate which parameters have been |
| 324 | * applied successfully. |
| 325 | * @param log_level This function will print to log at this level upon |
| 326 | * encountering errors. |
| 327 | * @param log_sender Optional sender name in the log. |
| 328 | * @param sock_name Optional name to help identify the socket in the log. |
| 329 | * |
| 330 | * @return PJ_SUCCESS if at least Layer 2 or Layer 3 setting is |
| 331 | * successfully set. If both Layer 2 and Layer 3 settings |
| 332 | * can't be set, this function will return error. |
| 333 | * |
| 334 | * @see pj_sock_apply_qos2() |
| 335 | */ |
| 336 | PJ_DECL(pj_status_t) pj_sock_apply_qos(pj_sock_t sock, |
| 337 | pj_qos_type qos_type, |
| 338 | pj_qos_params *qos_params, |
| 339 | unsigned log_level, |
| 340 | const char *log_sender, |
| 341 | const char *sock_name); |
| 342 | |
| 343 | /** |
| 344 | * Variant of #pj_sock_apply_qos() where the \a qos_params parameter is |
| 345 | * const. |
| 346 | * |
| 347 | * @see pj_sock_apply_qos() |
| 348 | */ |
| 349 | PJ_DECL(pj_status_t) pj_sock_apply_qos2(pj_sock_t sock, |
| 350 | pj_qos_type qos_type, |
| 351 | const pj_qos_params *qos_params, |
| 352 | unsigned log_level, |
| 353 | const char *log_sender, |
| 354 | const char *sock_name); |
| 355 | |
| 356 | /** |
| 357 | * Retrieve the standard mapping of QoS params for the specified traffic |
| 358 | * type. |
| 359 | * |
| 360 | * @param type The traffic type from which the QoS parameters |
| 361 | * are to be retrieved. |
| 362 | * @param p_param Pointer to receive the QoS parameters. |
| 363 | * |
| 364 | * @return PJ_SUCCESS on success or the appropriate error code. |
| 365 | */ |
| 366 | PJ_DECL(pj_status_t) pj_qos_get_params(pj_qos_type type, |
| 367 | pj_qos_params *p_param); |
| 368 | |
| 369 | |
| 370 | /** |
| 371 | * Retrieve the traffic type that matches the specified QoS parameters. |
| 372 | * If no exact matching is found, this function will return an |
| 373 | * approximation of the closest matching traffic type for the specified |
| 374 | * QoS parameters. |
| 375 | * |
| 376 | * @param param Structure containing QoS parameters to map into |
| 377 | * "standard" traffic types. |
| 378 | * @param p_type Pointer to receive the traffic type. |
| 379 | * |
| 380 | * @return PJ_SUCCESS on success or the appropriate error code. |
| 381 | */ |
| 382 | PJ_DECL(pj_status_t) pj_qos_get_type(const pj_qos_params *param, |
| 383 | pj_qos_type *p_type); |
| 384 | |
| 385 | |
| 386 | /** |
| 387 | * This is a low level API to set QoS parameters to the socket. |
| 388 | * |
| 389 | * @param sock The socket. |
| 390 | * @param param Structure containing QoS parameters to be applied |
| 391 | * to the socket. Upon return, the \a flags field |
| 392 | * of this structure will be set with bitmask value |
| 393 | * indicating which QoS settings have successfully |
| 394 | * been applied to the socket. |
| 395 | * |
| 396 | * @return PJ_SUCCESS if at least one field setting has been |
| 397 | * successfully set. If no setting can't be set, |
| 398 | * this function will return error. |
| 399 | */ |
| 400 | PJ_DECL(pj_status_t) pj_sock_set_qos_params(pj_sock_t sock, |
| 401 | pj_qos_params *param); |
| 402 | |
| 403 | /** |
| 404 | * This is a low level API to get QoS parameters from the socket. |
| 405 | * |
| 406 | * @param sock The socket. |
| 407 | * @param p_param Pointer to receive the parameters. Upon returning |
| 408 | * successfully, the \a flags field of this structure |
| 409 | * will be initialized with the appropriate bitmask |
| 410 | * to indicate which fields have been successfully |
| 411 | * retrieved. |
| 412 | * |
| 413 | * @return PJ_SUCCESS on success or the appropriate error code. |
| 414 | */ |
| 415 | PJ_DECL(pj_status_t) pj_sock_get_qos_params(pj_sock_t sock, |
| 416 | pj_qos_params *p_param); |
| 417 | |
| 418 | |
| 419 | /** |
| 420 | * @} |
| 421 | */ |
| 422 | |
| 423 | |
| 424 | PJ_END_DECL |
| 425 | |
| 426 | #endif /* __PJ_SOCK_QOS_H__ */ |
| 427 | |