1<!-- Creator : groff version 1.22.2 --> 2<!-- CreationDate: Thu Feb 2 17:04:41 2017 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title>mtcp_init</title> 17 18</head> 19<body> 20 21<h1 align="center">mtcp_init</h1> 22 23<a href="#NAME">NAME</a><br> 24<a href="#SYNOPSIS">SYNOPSIS</a><br> 25<a href="#DESCRIPTION">DESCRIPTION</a><br> 26<a href="#RETURN VALUE">RETURN VALUE</a><br> 27<a href="#NOTES">NOTES</a><br> 28<a href="#AUTHORS">AUTHORS</a><br> 29<a href="#SEE ALSO">SEE ALSO</a><br> 30<a href="#COLOPHON">COLOPHON</a><br> 31 32<hr> 33 34 35<h2>NAME 36<a name="NAME"></a> 37</h2> 38 39 40<p style="margin-left:11%; margin-top: 1em">mtcp_init 41− initialize the mOS stack</p> 42 43<h2>SYNOPSIS 44<a name="SYNOPSIS"></a> 45</h2> 46 47 48<p style="margin-left:11%; margin-top: 1em"><b>#include 49<mtcp_api.h></b></p> 50 51<p style="margin-left:11%; margin-top: 1em"><b>int 52mtcp_init(char *</b><i>config_file</i><b>);</b></p> 53 54<h2>DESCRIPTION 55<a name="DESCRIPTION"></a> 56</h2> 57 58 59 60<p style="margin-left:11%; margin-top: 1em"><b>mtcp_init</b>() 61call is used to set the stack parameters of an mOS-based 62application. These parameters are loaded inside the process 63via a startup configuration file, <i>config_file.</i> A 64developer is required to first call <b>mtcp_init</b>() 65function before he/she can invoke any follow-up mOS 66functions in his/her application.</p> 67 68<p style="margin-left:11%; margin-top: 1em">A typical 69<i>config_file</i> is composed of at least two mOS 70configuration blocks. The app block sets the configuration 71parameters of the application that employs the underlying 72mOS stack. A typical instance of an app block is illustrated 73below.</p> 74 75 76<p style="margin-left:11%; margin-top: 1em">####################### 77<br> 78# APPLICATION OPTIONS # <br> 79####################### <br> 80# application to run <br> 81application { <br> 82type = end <br> 83run = epwget <br> 84core_mask = 0x000F <br> 85}</p> 86 87<p style="margin-left:11%; margin-top: 1em">A user can 88populate the app block with the following parameters:</p> 89 90<table width="100%" border="0" rules="none" frame="void" 91 cellspacing="0" cellpadding="0"> 92<tr valign="top" align="left"> 93<td width="11%"></td> 94<td width="14%"> 95 96 97<p style="margin-top: 1em">type</p></td> 98<td width="12%"></td> 99<td width="63%"> 100 101 102<p style="margin-top: 1em">The type of application that the 103user wants to run. An application can either be an endpoint 104application (’end’) such as an mTCP client or 105mTCP server, or be a middlebox application 106(’monitor’).</p> </td></tr> 107<tr valign="top" align="left"> 108<td width="11%"></td> 109<td width="14%"> 110 111 112<p>run</p></td> 113<td width="12%"></td> 114<td width="63%"> 115 116 117<p>The name of the binary to execute.</p></td></tr> 118<tr valign="top" align="left"> 119<td width="11%"></td> 120<td width="14%"> 121 122 123<p>core_mask</p></td> 124<td width="12%"></td> 125<td width="63%"> 126 127 128<p>The CPU bitmask where you want to run the application. 129The mask 0x000F denotes that the user wants to run a 130single-process, 4-threaded application on the first four 131cores of the CPU (CPU 0~3).</p></td></tr> 132</table> 133 134<p style="margin-left:11%; margin-top: 1em">The user can 135run one or more monitoring applications at the same 136time.</p> 137 138<p style="margin-left:11%; margin-top: 1em">A mos block 139adjusts the internal parameters of the mOS stack.</p> 140 141 142<p style="margin-left:11%; margin-top: 1em">####################### 143<br> 144# MOS-RELATED OPTIONS # <br> 145#######################</p> 146 147<p style="margin-left:11%; margin-top: 1em">mos { <br> 148forward = 1</p> 149 150 151<p style="margin-left:11%; margin-top: 1em">####################### 152<br> 153##### I/O OPTIONS ##### <br> 154####################### <br> 155# number of memory channels per socket [mandatory for DPDK] 156<br> 157nb_mem_channels = 4</p> 158 159<p style="margin-left:11%; margin-top: 1em"># devices used 160for MOS applications [mandatory] <br> 161netdev { <br> 162dpdk0 0x000F <br> 163dpdk1 0x000F <br> 164}</p> 165 166 167<p style="margin-left:11%; margin-top: 1em">####################### 168<br> 169### LOGGING OPTIONS ### <br> 170####################### <br> 171# NICs to print network statistics per second <br> 172# if enabled, mTCP will print xx Gbps and xx pps for RX and 173TX <br> 174stat_print = dpdk0 dpdk1</p> 175 176<p style="margin-left:11%; margin-top: 1em"># A directory 177contains MOS system log files <br> 178mos_log = logs/</p> 179 180<p style="margin-left:11%; margin-top: 1em"># dpdk0 and 181dpdk1 will forward traffic in either direction <br> 182nic_forward_table { <br> 183dpdk0 dpdk1 <br> 184}</p> 185 186<p style="margin-left:11%; margin-top: 1em">}</p> 187 188<p style="margin-left:11%; margin-top: 1em">A user can 189populate an mOS configuration block with the following 190parameters:</p> 191 192<table width="100%" border="0" rules="none" frame="void" 193 cellspacing="0" cellpadding="0"> 194<tr valign="top" align="left"> 195<td width="11%"></td> 196<td width="26%"> 197 198 199<p style="margin-top: 1em">forward</p></td> 200<td width="9%"></td> 201<td width="52%"> 202 203 204<p style="margin-top: 1em">Setting this option to 1 enables 205packet forwarding (for middlebox operations). Keep this 206value to 0 for endpoint mTCP applications.</p></td> 207<td width="2%"> 208</td></tr> 209<tr valign="top" align="left"> 210<td width="11%"></td> 211<td width="26%"> 212 213 214<p>nb_mem_channels</p></td> 215<td width="9%"></td> 216<td width="52%"> 217 218 219<p>(Mandatory for DPDK) nb_mem_channels parameter specifies 220the number of memory channels per CPU socket. Please refer 221to DPDK user guide, on tuning this parameter for performance 222optimizations.</p> </td> 223<td width="2%"> 224</td></tr> 225<tr valign="top" align="left"> 226<td width="11%"></td> 227<td width="26%"> 228 229 230<p>netdev</p></td> 231<td width="9%"></td> 232<td width="52%"> 233 234 235<p>netdev parameter block specifies the network interfaces 236(or device ports) used for mOS applications. Each line 237contains the mapping of a network interface and CPU core 238mask. In the example above, it uses two DPDK-assisted 239network interfaces (dpdk0 and dpdk1), and CPU cores 0~3 240receive/transmit traffic from/to the first 4 (0~3) hardware 241queues of the NIC. We program our DPDK driver to use 242symmetric RSS algorithm to distribute traffic across the 243cores. This ensures that the same CPU gets to examine 244packets of both flows of the connection.</p></td> 245<td width="2%"> 246</td></tr> 247<tr valign="top" align="left"> 248<td width="11%"></td> 249<td width="26%"> 250 251 252<p>stat_print</p></td> 253<td width="9%"></td> 254<td width="52%"> 255 256 257<p>stat_print parameter specifies the network interfaces 258which the application is interested in displaying runtime 259monitor statistics.</p></td> 260<td width="2%"> 261</td></tr> 262<tr valign="top" align="left"> 263<td width="11%"></td> 264<td width="26%"> 265 266 267<p>mos_log</p></td> 268<td width="9%"></td> 269<td width="52%"> 270 271 272<p>mos_log parameter specifies the path to a directory 273where the mOS system writes extra logging data.</p></td> 274<td width="2%"> 275</td></tr> 276<tr valign="top" align="left"> 277<td width="11%"></td> 278<td width="26%"> 279 280 281<p>nic_forward_table</p></td> 282<td width="9%"></td> 283<td width="52%"> 284 285 286<p>nic_forward_table parameter block specifies the static 287Ethernet traffic forwarding rules when the mOS middlebox 288application is set in inline mode (Running Monitor 289Applications in Inline Mode). If enabled, each line accepts 290a pair of DPDK-registered NIC interfaces via which the 291traffic can later be forwarded in either direction. Each 292interface should have one-to-one mapping with another. In 293the example above, traffic is switched from dpdk0 to dpdk1 294and vice versa. The middlebox is configured as a 295’bump-in-the-wire’.</p> </td> 296<td width="2%"> 297</td></tr> 298<tr valign="top" align="left"> 299<td width="11%"></td> 300<td width="26%"> 301 302 303<p>max_concurrency</p></td> 304<td width="9%"></td> 305<td width="52%"> 306 307 308<p>max_concurrency specifies the maximum number of 309concurrent flows a middlebox can examine per CPU core. This 310parameter is used for preallocating the memory for flows. 311[default value: 100000]</p></td> 312<td width="2%"> 313</td></tr> 314<tr valign="top" align="left"> 315<td width="11%"></td> 316<td width="26%"> 317 318 319<p>no_ring_buffers</p></td> 320<td width="9%"></td> 321<td width="52%"> 322 323 324<p>no_ring_buffers determines whether the TCP ring buffer 325should be disabled. For mOS endpoint (mTCP) applications, 326mOS always require the socket buffers for the application. 327For middlebox applications, you can disable the receive-side 328socket buffer by putting no_ring_buffers = 1. [default 329value: 0 (ring buffer is enabled by default)]</p></td> 330<td width="2%"> 331</td></tr> 332<tr valign="top" align="left"> 333<td width="11%"></td> 334<td width="26%"> 335 336 337<p>rmem_size</p></td> 338<td width="9%"></td> 339<td width="52%"> 340 341 342<p>Specifies the size of receive buffer per socket in bytes 343[default value: 8192 B].</p></td> 344<td width="2%"> 345</td></tr> 346<tr valign="top" align="left"> 347<td width="11%"></td> 348<td width="26%"> 349 350 351<p>wmem_size</p></td> 352<td width="9%"></td> 353<td width="52%"> 354 355 356<p>Specifies the size of send buffer per socket in bytes 357[default value: 8192 B].</p></td> 358<td width="2%"> 359</td></tr> 360<tr valign="top" align="left"> 361<td width="11%"></td> 362<td width="26%"> 363 364 365<p>tcp_tw_interval</p></td> 366<td width="9%"></td> 367<td width="52%"> 368 369 370<p>Specifies the TCP timewait interval value in seconds. 371TCP timewait interval is the allowed time for a connection 372to be in the TIME_WAIT state. For mOS endpoint (mTCP) 373applications, user can set it as an arbitrary value larger 374than 0 to guarantee graceful shutdown. For monitoring 375applications, the user may set it to 0 if she is not 376interested in monitoring the flow after TIME_WAIT state. 377[default value: 0s]</p></td> 378<td width="2%"> 379</td></tr> 380<tr valign="top" align="left"> 381<td width="11%"></td> 382<td width="26%"> 383 384 385<p>tcp_timeout</p></td> 386<td width="9%"></td> 387<td width="52%"> 388 389 390<p>Specifies the TCP timeout value in seconds. This 391parameter determines the maximum allowed time for any flows 392to exist without any packet reception. In other words, mOS 393middlebox stops monitoring the connection after tcp_timeout 394idle period. You can set tcp_timeout = -1 to disable the 395timeout checking. For mOS endpoint (mTCP) applications, 396tcp_timeout serves as a timeout period for connections that 397are in active open states (SYN_SENT states). [default value: 39830s]</p> </td> 399<td width="2%"> 400</td></tr> 401</table> 402 403<h2>RETURN VALUE 404<a name="RETURN VALUE"></a> 405</h2> 406 407 408<p style="margin-left:11%; margin-top: 1em">Returns 0 on 409success; -1 on failure.</p> 410 411<h2>NOTES 412<a name="NOTES"></a> 413</h2> 414 415 416<p style="margin-left:11%; margin-top: 1em">See 417<i>http://mos.kaist.edu/guide/walkthrough/05_configuration.html</i> 418to view example startup mOS configuration file.</p> 419 420<h2>AUTHORS 421<a name="AUTHORS"></a> 422</h2> 423 424 425<p style="margin-left:11%; margin-top: 1em">mOS development 426team <[email protected]></p> 427 428<h2>SEE ALSO 429<a name="SEE ALSO"></a> 430</h2> 431 432 433 434<p style="margin-left:11%; margin-top: 1em"><b>mtcp_destroy</b>()</p> 435 436<h2>COLOPHON 437<a name="COLOPHON"></a> 438</h2> 439 440 441<p style="margin-left:11%; margin-top: 1em">This page is 442part of mOS release 0.3 <i>docs</i> section. A description 443of the project, and information about reporting bugs, can be 444found at http://mos.kaist.edu/.</p> 445<hr> 446</body> 447</html> 448