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