216 lines
14 KiB
HTML
216 lines
14 KiB
HTML
<!-- HTML header for doxygen 1.9.1-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.15.0"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>L4Re Operating System Framework: l4vio_switch, a virtual network switch</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<script type="text/javascript" src="cookie.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
|
<link href="l4re-awesome.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectlogo"><img alt="Logo" src="L4Re_rgb_logo_quer_hg_h55.png"/></td>
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">L4Re Operating System Framework
|
|
</div>
|
|
<div id="projectbrief">Interface and Usage Documentation</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.15.0 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
</script>
|
|
<script type="text/javascript">
|
|
$(function() { codefold.init(); });
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search',true);
|
|
$(function() { init_search(); });
|
|
});
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
$(function(){initNavTree('l4re_servers_vio_switch.html','',''); });
|
|
</script>
|
|
<div id="container">
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">l4vio_switch, a virtual network switch </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="md_pkg_2virtio-net-switch_2doc_2usage"></a></p>
|
|
<p>The virtual network switch connects multiple clients with a virtual network connection. It uses Virtio as the transport mechanism. Each virtual switch port implements the host-side of a Virtio network device (virtio-net).</p>
|
|
<p>The virtual network switch can be setup to feature exactly one monitor port. All traffic passing through the switch is mirrored to the monitor port. The monitor port is read-only, and has no TX capability. An optional packet filter can be configured and implemented to filter data sent to the monitor port.</p>
|
|
<h1>Configuration</h1>
|
|
<p>Certain features of the virtual network switch are configurable at compile-time. Configuration is done through the build-time configuration of the <a class="el" href="namespaceL4Re.html" title="L4Re C++ Interfaces.">L4Re</a> build tree.</p>
|
|
<h1>Starting the service</h1>
|
|
<p>The virtual network switch can be started in Ned like this: </p><pre class="fragment">local switch = L4.default_loader:new_channel();
|
|
L4.default_loader:start(
|
|
{
|
|
caps = {
|
|
svr = switch:svr(),
|
|
},
|
|
},
|
|
"rom/l4vio_switch");
|
|
</pre><p>First a communication channel (<span class="tt">switch</span>) is created which is used to create virtual network ports. It is connected to the switch component via its mandatory <span class="tt">svr</span> capability. See the section below on how to create a new virtual port and connect a client to it.</p>
|
|
<h2>Options</h2>
|
|
<p>In the example above the virtual network switch is started in its default configuration with a maximum of 5 virtual ports. To customize the configuration the virtual network switch accepts the following command line options:</p>
|
|
<ul>
|
|
<li><p class="startli"><span class="tt">-D <component=level></span>, <span class="tt">--debug <component=level></span></p>
|
|
<p class="startli">Configure individual debug levels per component. Allowed components are: </p><blockquote class="doxtable">
|
|
<p><span class="tt">core</span>, <span class="tt">virtio</span>, <span class="tt">port</span>, <span class="tt">request</span>, <span class="tt">queue</span>, <span class="tt">packet</span> </p>
|
|
</blockquote>
|
|
<p class="startli">Possible debug levels with increasing verbosity are: </p><blockquote class="doxtable">
|
|
<p><span class="tt">quiet</span>, <span class="tt">warn</span>, <span class="tt">info</span>, <span class="tt">debug</span>, <span class="tt">trace</span> </p>
|
|
</blockquote>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li><p class="startli"><span class="tt">-m</span>, <span class="tt">--mac</span></p>
|
|
<p class="startli">Ignored. Provided for compatibility with older switch versions.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-M</span></p>
|
|
<p class="startli">Do not assign a random MAC address to ports by default. It is always possible to set an explicit MAC address by passing the <span class="tt">mac=</span> to the factory call, regardless of this option. If <span class="tt">-M</span> is passed and no <span class="tt">mac=</span> address was given, it is the responsibility of the Virtio driver to choose an appropriate address.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-p <num></span>, <span class="tt">--ports <num></span></p>
|
|
<p class="startli">Set the maximum number of virtual ports. The default is 5.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-q</span>, <span class="tt">--quiet</span></p>
|
|
<p class="startli">Silence all output except for error messages.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-s <num></span>, <span class="tt">--size <num></span></p>
|
|
<p class="startli">Set the maximum queue size for the device-side Virtio queues. Must be a power of 2 in the range of 1 to 32768 inclusive.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-v</span>, <span class="tt">--verbose</span></p>
|
|
<p class="startli">Increase the global verbosity level. Individual levels per component can be set using the <span class="tt">-D</span> option.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">-d <cap_name></span>, <span class="tt">--register-ds <cap_name></span> Register a trusted dataspace capability. If this option gets used, it is not possible to communicate with the server via dataspaces other than the registered ones. Can be used multiple times for multiple dataspaces.</p>
|
|
<p class="startli">The option parameter is the name of a dataspace capability.</p>
|
|
</li>
|
|
</ul>
|
|
<h2>Hardware devices</h2>
|
|
<p>To plug hardware devices into the switch, provide a Vbus capability with the name <span class="tt">vbus</span> when starting the switch. To use this feature, you have to enable the <span class="tt">VNS_IXL</span> config option.</p>
|
|
<h1>Connecting a client</h1>
|
|
<p>First, a virtual network port has to be created using the following Ned-Lua function. It has to be called on the communication channel called <span class="tt">switch</span>, which has been created earlier. </p><pre class="fragment">create(obj_type, ["ds-max=<max>", "name=<name>", "type=<port type>",
|
|
"vlan=<options>", "mac=<mac_address>"])
|
|
</pre><ul>
|
|
<li><p class="startli"><span class="tt">obj_type</span></p>
|
|
<p class="startli">The type of object that should be created by the switch. The type must be a positive integer. Currently the following objects are supported:</p><ul>
|
|
<li><span class="tt">0</span>: Virtual switch port</li>
|
|
</ul>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">ds-max=<max></span></p>
|
|
<p class="startli">Specifies the upper limit of the number of dataspaces the client is allowed to register with the virtual network switch for Virtio DMA.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">name=<name></span></p>
|
|
<p class="startli">Sets the name of port in debug messages to <span class="tt"><name></span>. A name may consist of at most 19 characters, all other characters are dropped. If there is enough space left, the name will get a postfix of "[<port number>]", e.g. "name=foo" -> foo[1].</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">type=<port type></span></p>
|
|
<p class="startli">Optionally specify the port type, either <span class="tt">normal</span> or a <span class="tt">monitor</span> port. Valid types are <span class="tt">[monitor|normal]</span>. The default is <span class="tt">type=normal</span> (if no type is given).</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">vlan=(access=<vlan id>|trunk=[<vlan id>[,<vlan id>]*])</span></p>
|
|
<p class="startli">Configure the port to participate in an IEEE 802.1Q compatible VLAN. Fundamentally there are two types of ports: access ports and trunk ports:</p><ul>
|
|
<li><p class="startli"><span class="tt">vlan=access=<vlan id></span></p>
|
|
<p class="startli">Configures the port as access port for VLAN <span class="tt"><vlan id></span> where the id must be a decimal number greater than 0 and less than 4095 in accordance to the standard. Packets on an access port belong to the configured VLAN and are only forwarded to ports that belong to the same VLAN or trunk ports that participate in the particular VLAN. The packets on this port will not have a VLAN tag attached to them so that a guest connected to this port does not see that the port is part of a VLAN.</p>
|
|
<p class="startli">An optional monitor port will see packets from an access port as VLAN tagged packets with the <span class="tt"><vlan id></span> given for the port.</p>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">vlan=trunk=all|[<vlan id>[,<vlan id>]*]</span></p>
|
|
<p class="startli">Configures the port as trunk port. It participates either in all VLANs, if specified by the keyword 'all', or in the list of VLANs given as comma separated list. There must be no whitespace in the list. Each id must be a decimal number greater than 0 and less than 4095 in accordance to the standard. Outgoing packets on this port will be tagged with an IEEE 802.1Q compatible tag. Incoming packets must be tagged with a VLAN tag from the given list. Packets that have no tag or a tag not in the vlan id list are dropped silently. They are not forwarded to the monitor port either.</p>
|
|
<p class="startli">Currently there is no support for IEEE 802.1p. The PCP and DEI sub-fields in the TCI field will be set to zero on outgoing packets and are ignored for incoming packets.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><p class="startli"><span class="tt">mac=xx:xx:xx:xx:xx:xx</span></p>
|
|
<p class="startli">Explicitly sets the MAC address of the port. It will be checked that no other port on the switch has the same address. It is the responsibility of the user to ensure the validity of the address and its global uniqueness, though.</p>
|
|
</li>
|
|
</ul>
|
|
<p>If the <span class="tt">create()</span> call is successful a new capability which references a virtual switch port is returned. A client uses this capability to talk to the virtual network switch using the Virtio network protocol.</p>
|
|
<p>Here are couple of examples on how to create ports with different properties: </p><pre class="fragment">-- normal port with at most 4 data spaces
|
|
net0 = switch:create(0, "ds-max=4")
|
|
-- like the previous but with name foo
|
|
net0 = switch:create(0, "ds-max=4", "name=foo")
|
|
-- like the previous but the port is a monitor port
|
|
net0 = switch:create(0, "ds-max=4", "name=foo", "type=monitor")
|
|
-- normal port with 4 data spaces as access port to VLAN 1
|
|
net0 = switch:create(0, "ds-max=4", "name=vl1", "vlan=access=1")
|
|
-- normal port with 4 data spaces as trunk port participating in VLAN 1 & 2
|
|
net0 = switch:create(0, "ds-max=4", "name=vl1", "vlan=trunk=1,2")
|
|
</pre> </div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<div id="page-nav" class="page-nav-panel">
|
|
<div id="page-nav-resize-handle"></div>
|
|
<div id="page-nav-tree">
|
|
<div id="page-nav-contents">
|
|
</div><!-- page-nav-contents -->
|
|
</div><!-- page-nav-tree -->
|
|
</div><!-- page-nav -->
|
|
</div><!-- container -->
|
|
<!-- HTML footer for doxygen 1.9.1-->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="navelem"><a href="l4re_servers.html">L4Re Servers</a></li>
|
|
<li class="footer">Generated on <span class="timestamp"></span> for L4Re Operating System Framework by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|