Commit 043a1b92 authored by David Johnson's avatar David Johnson
Browse files

Add a netfpga tutorial.

parent c19aa5c7
<!--
EMULAB-COPYRIGHT
Copyright (c) 2007 University of Utah and the Flux Group.
All rights reserved.
-->
<center>
<h1>Using NetFPGA programmable network devices in Emulab</h1>
</center>
The <a href="http://netfpga.org">NetFPGA</a> is now integrated into Emulab, and
is available to external researchers for remote experimentation. You can
allocate a NetFPGA in an <i>ns</i> file in a similar manner to how you allocate
other Emulab resources. NetFPGAs can be configured as part of an arbitrary
topology with end nodes, links and LANs, traffic generators, and other standard
Emulab options.
<p>
Currently, we've installed 2 NetFPGAs into
<emph><a href="/shownodetype.php3?node_type=pc3000">pc3000</a></emph>s
(although we plan to install more to enable larger routing experiments). You
can check if the NetFPGAs are available for your experiment by looking at the
<a href="https://www.emulab.net/nodecontrol_list.php3">Node Control Center</a>.
<h2>Contents</h2>
<ul>
<li> <a href="#GettingStarted">Getting Started in Emulab</a>
<li> <a href="#Creating">Creating an experiment with NetFPGA routers</a>
<li> <a href="#CustomApp">Loading your custom bitfile on a NetFPGA</a>
<li> <a href="#testexpt">Sample Experiment using a NetFPGA in Emulab</a>
<li> <a href="#nodeusage">Node usage policies</a>
<li> <a href="#notes">Setup Notes</a>
</ul>
<hr>
<a NAME="GettingStarted"></a>
<center>
<h2>Getting Started with NetFPGAs in Emulab</h2>
</center>
<p>
To start using NetFPGA nodes in Emulab, you first need an account
in Emulab. See <a href="http://www.emulab.net/doc.php3">
Emulab Documentation </a> for more details; especially if you are
using Emulab for the first time.
You will also want to familiarize yourself with how to program and interact
with NetFPGAs; <a href="http://netfpga.org/static/guide.html">this guide</a> is
a good starting point.
</p>
<hr>
<a NAME="Creating"></a>
<center>
<h2>Creating a NetFPGA experiment</h2>
</center>
Here's a sample ns file, which allocates a NetFPGA node and two
end-nodes connected in a simple linear topology.
<code><pre>
# Boilerplate
source tb_compat.tcl
set ns [new Simulator]
# Create a NetFPGA node
set nfrouter [$ns node]
# Set its hardware type to NetFPGA
tb-set-hardware $nfrouter netfpga2
# Name the NetFPGA host, bind it to the NetFPGA node, and
# set its OS.
set nfhost [$ns node]
tb-bind-parent $nfrouter $nfhost
tb-set-node-os $nfhost FC6-NETFPGA
# Create end nodes
set n0 [$ns node]
set n1 [$ns node]
# Create links between the end nodes and the NetFPGA
set link0 [$ns duplex-link $n0 $nfrouter 1Gb 0ms DropTail]
set link1 [$ns duplex-link $n1 $nfrouter 1Gb 0ms DropTail]
# Set up static routing on all nodes,
$ns rtproto Static
# Boilerplate
$ns run
</pre></code>
When the above ns file is submitted, Emulab creates an experiment with
the requested nodes, creates the topology specified above, and configures the
NetFPGA nodes as described below.
<ul>
<li>We automatically reprogram the CPCI and upload the IPv4 reference router
bitfile (created by researchers at Stanford University) to the NetFPGA
board.
<li>If you use static routing in your <emph>ns</emph> file, routes are
automatically generated between all nodes; interface
configuration information like IP addresses is generated for the
NetFPGA interfaces as well as other nodes. Emulab uses this to
configure the NetFPGA interfaces and initialize the routing and ARP tables.
<li>Also, if you use static routing, we start up the
<a href="http://netfpga.org/static/guide.html#SCONE_Walkthrough">SCONE</a>
userspace router, which handles exception packets from the router hardware,
including ARPs, and maintains a copy of the routing table in userspace. SCONE
also supports a subset of OSPF, named PW-OSPF, and automatically sends OSPF
hello messages on the NetFPGA interfaces.
</ul>
More complicated topologies with LANs, emulated links, routers, and more,
can be similarly created to test your NetFPGA-based application.
<hr>
<a NAME="CustomApp"></a>
<center>
<h2>Running your custom bitfile on the NetFPGA</h2>
</center>
To customize the router's functionality inside the hardware, you'll need to
customize the existing gateware source, or write your own, and compile it into
a bitfile as described in the
<a href="http://netfpga.org/static/guide.html">NetFPGA guide</a>. You can
upload the bitfile to your NetFPGA via the command
<code><pre>
/usr/local/bin/nf2_download &lt;path-to-your-bitfile&gt;
</pre></code>
The <emph>FC6-NetFPGA</emph> image does not have the tools necessary to
synthesize bitfiles installed by default, so you'll need to install them in
your own image if you plan to use Emulab nodes to compile your source.
<hr>
<a NAME="nodeusage"></a>
<center>
<h2>Node Usage Policies</h2>
</center>
Emulab has certain <a
href="http://www.emulab.net/docwrapper.php3?docname=swapping.html">
Node Usage Policies</a> to facilitate sharing of resources among
experimenters. Since we have limited number of boards available,
please use resources in accordance with these policies.
<hr>
<a NAME="notes"></a>
<center>
<h2>Setup Notes</h2>
</center>
<ul>
<li> The NetFPGA PHY chips support only Gigabit ethernet. Consequently, you
must connect them only to 1Gb links in your NS file. Since we don't
support shaping on links with speeds faster than 100Mb, you also can't
insert shape the link coming into your NetFPGA. If you really want to
experiment with shaped links of 100Mb or below flowing into your NetFPGA,
you can just add a "dummy" node between the real end node and the NetFPGA,
and customize the link between the "dummy" node and the real end node.
<p>
<li> NetFPGAs are not real Emulab PCs. Rather, they are "subnodes" of a host
PC. This means that to customize the NetFPGA, you should login to its host
PC.
<p>
<li> Our default disk image for NetFPGA host PCs, <emph>FC6-STD</emph>, is
based on Fedora Core 6, not CentOS (as suggested in the NetFPGA guide).
Furthermore, we used a much newer kernel than suggested in the guide
(2.6.18.1) to build the nf2 driver.
<p>
<li> We automatically configure the NetFPGA device when its host PC boots via
the <code>/usr/local/etc/emulab/netfgpactl</code> script. This script
obtains configuration information from Emulab (such as IP addresses,
routes, etc.) for the NetFPGA ports, sets up the routing table, starts up
SCONE, etc. It invalidates all existing entries in the routing and
ARP tables before setting the routes.
<p>
<li> The nf2 driver presents 4 user-visible (i.e., with <code>ifconfig</code>)
interfaces for each NetFPGA card. These interfaces all have MAC addresses
like <code>00:4E:46:32:43:0(0-N)</code>. However, the actual MAC chips
also need their own real MAC addresses. To ensure consistent naming for
these MAC addresses, we set the first byte to <code>0x02</code> (a reserved
bit to indicate "local" address assignment), and change the fourth byte to
the numeric Emulab id of the NetFPGA node (i.e., for "netfpga5", the 4th
byte would be set to <code>0x05</code>).
</ul>
......@@ -56,6 +56,9 @@
<li> <a href="docwrapper.php3?docname=gnuradio.html">
Using GNU Radio USRP hardware</a>
<img src="../new.gif" alt="&lt;NEW&gt;">
<li> <a href="docwrapper.php3?docname=netfpga.html">
Using NetFPGA hardware</a>
<img src="../new.gif" alt="&lt;NEW&gt;">
</ul>
<li> <a href="#BatchMode">Batch Mode Experiments</a>
<li> <a href="#CustomOS">Creating your own disk image</a>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment