wiki:WARPLab/QuickStart

Version 26 (modified by murphpo, 11 years ago) (diff)

--

Quick Start

System Requirements

Setting up the WARPLab 7 Framework

  1. Download the latest WARPLab Reference Design Release (Download) and unzip it to a location of your choosing.
  2. Open MATLAB and change the current path to the M_Code_Reference directory from the downloaded archive.
  3. Run wl_setup on the MATLAB command line.
  4. Follow the prompts to configure your WARPLab environment.

Hardware Setup

  • For your PC:
    1. Assign one of your NICs to the manual IP address specified in the wl_setup step above (default 10.0.0.250)
    2. Connect the NIC to a 1Gb Ethernet switch
  • For WARP v3 nodes:
    1. Connect ETH_A to the 1Gb Ethernet switch your PC is connected to.
    2. Set the user DIP switch to a unique value on each node, starting at 0
    3. Configure the FPGA with the Reference Design. The reference bitstreams are included in the Bitstreams_Reference folder from the downloaded archive. Find the bitstream appropriate for your hardware and program the .bit file to the board using the Xilinx iMPACT tool. The .bin file can be used to configure an SD card with the design (see the SD config howto for help using the .bin file).
      1. On boot each node will display its node ID on the right hex display
      2. The bottom green LED will blink until the Ethernet link is up
      3. All four green LEDs will blink when the node is ready to accept commands from MATLAB

Examples

  1. Confirm everything is ready by copying and pasting the following lines to the MATLAB command line:
    clear
    N = 1;
    nodes = wl_initNodes(N);
    wl_nodeCmd(nodes,'identify');
    disp(nodes)
    

Note: N can be changed to the number of nodes in your network. When you run these lines of code, you should see the User I/O LEDs on your N nodes blink as a result of the identify? command. Additionally, you should see your nodes object vector print status messages to the screen. For N = 2, your status display should be similar to:

Displaying properties of 2 wl_node objects:
|  ID |  WLVER |  HWVER |    Serial # |  Ethernet MAC Addr |
------------------------------------------------------------
|   0 |  7.0.0 |      3 |  W3-a-00027 |  40-D8-55-04-20-36 |
------------------------------------------------------------
|   1 |  7.0.0 |      3 |  W3-a-00041 |  40-D8-55-04-20-52 |
------------------------------------------------------------
  1. If the previous stepped work, you should now try one of the M-Code Examples?.

Getting Help

There are a few resources for getting help with using WARPLab for your own designs:

  1. The wl_cmd_list is a function that allows you to display all commands than an object supports.
  2. The wl_cmd_doc is a function that will display documentation for a particular command.
  3. The WARP forums (http://warpproject.org/forums/) are a great place to ask questions.

Tips

MATLAB Object Oriented Syntax

Throughout the WARPLab MATLAB code, you will see a mix of equivalent ways of calling methods to various objects. Suppose you have an object obj in your workspace and that object has a method method. You can call this method in two completely equivalent ways:

obj.method()

or

method(obj)

As a more concrete example, consider the quick start step above that called the command wl_nodeCmd(nodes,'identify');. An equivalent way of issuing this command to the nodes in the network is nodes.wl_nodeCmd('identify');

Jumbo Frames

The WARP hardware design supports Ethernet packets up to 9000 bytes. Any Ethernet packet larger than 1500 bytes is considered a "jumbo frame" and support for these jumbo frames among consumer NICs and switches is limited. To see if your hardware supports jumbo frames, increase the MTU setting on your computer to the maximum allowed setting. Then, two tests can determine the maximum usable payload: (a) a ping test, and (b) a WARPLab test.

Ping Test

Once the MTU on your machine is raised to its maximum, you can use pings from your computer to determine whether your switch and NIC can actually send and receive jumbo frames. Make sure you have a board configured with the WARPLab bitstream and a DIP switch of '0' (making its IP address 10.0.0.1).

Windows: Open the command line 'cmd.exe' and type the following:

>ping -l 8000 10.0.0.1

This will send 8000 byte pings to the board. If the board responds, Windows will tell you how many bytes were actually returned. For example, we receive the following using one of our PCs:

Pinging 10.0.0.1 with 8000 bytes of data:
Reply from 10.0.0.1: bytes=8000 time=2ms TTL=32
Reply from 10.0.0.1: bytes=8000 time=2ms TTL=32
Reply from 10.0.0.1: bytes=8000 time=2ms TTL=32
Reply from 10.0.0.1: bytes=8000 time=2ms TTL=32

This shows that the 8000 byte ping packet was returned, and you computer and switch appear to support communicating with a WARP board with jumbo frames. If, however, you receive ping responses that look like this:

Pinging 10.0.0.1 with 8000 bytes of data:
Reply from 10.0.0.1: bytes=1472 (sent 8000) time<1ms TTL=32
Reply from 10.0.0.1: bytes=1472 (sent 8000) time<1ms TTL=32
Reply from 10.0.0.1: bytes=1472 (sent 8000) time<1ms TTL=32
Reply from 10.0.0.1: bytes=1472 (sent 8000) time<1ms TTL=32

Then only 1472 bytes were returned of the sent 8000. This means that the packets were fragmented and that the MTU was not set high enough to support the 8000 byte ping packet.

Linux/OSX: Open a terminal and type the following:

> ping -s 8000 10.0.0.1

This will send 8000 byte pings to the board. The board should respond to these pings and return something similar to the following:

PING 10.0.0.1 (10.0.0.1): 8000 data bytes
5976 bytes from 10.0.0.1: icmp_seq=1 ttl=32 time=2.356 ms
wrong total length 5996 instead of 8028

If, however, the MTU is not set high enough to support the 8000 byte pings, then the board may respond with a smaller reply:

PING 10.0.0.1 (10.0.0.1): 8000 data bytes
8008 bytes from 10.0.0.1: icmp_seq=0 ttl=32 time=2.928 ms
8008 bytes from 10.0.0.1: icmp_seq=1 ttl=32 time=3.071 ms

WARPLab Test

If the ping test indicates that your PC and your Ethernet switch support jumbo frames, the next step is to see if WARPLab works with jumbo frames. When node objects are first set up in a WARPLab script, they run a test with their associated boards to see what maximum payload size can be supported. First, re-run the wl_setup function in M_Code_Reference and select that you would like to enable jumbo frame support. Next, ensure one WARP board is programmed with the WARPLab bitstream and configured with DIP switch '0'. Then, copy and paste the following lines to the MATLAB command line:

clear;
node = wl_initNodes(1);
disp(node.transport.maxPayload)

This will display the payload size the WARPLab has configured itself to use. For one of our PCs, this value returns as 8960, showing the jumbo frame support is correctly working.

Known Hardware Compatibility

It is impossible to form a definitive list of hardware that is compatible with jumbo frame support, but we will maintain a list of observed setups and their compatibility. If you try jumbo frames and have a hardware setup that does or does not work with them, please post to the WARP forums so we can add them to the list.

Known Compatible:

  • Dell workstation, Windows 7 64-bit, Intel(R) 82573LB NIC
  • Netgear GS105 gigabit switch

Known Partially Compatible:

  • Apple 2013 Macbook Pro, OSX 10.8.3, Apple Thunderbolt to Gigabit Ethernet Adapter
    • Appears to have a "hidden" MTU maximum around 8000, despite the GUI letting you choose 9000.
  • Apple 2011 Mac Mini, OSX 10.8.3, Broadcom 57765-B0
    • Appears to work for MTU < 7000. There were problems with larger MTUs, but those problems may be attributed to a bad switch.

Known Incompatible:

  • Dell workstation, Windows 7 64-bit, Broadcom NetXtreme Gigabit Ethernet BCM5755
  • Apple 2010 Macbook Pro, OSX 10.8.3, Broadcom 5764-B0

pnet Toolbox

By default, WARPLab will use built-in java routines for performing network I/O. pnet, a custom UDP mex toolbox for matlab, is also supported, but the latest version is required. pnet can offer modestly higher performance than the built-in java routines, but the usage of WARPLab is otherwise identical. Note: these performance gains are negligible for jumbo frame packets near 9000 bytes on length. If you want to use pnet, please perform the following steps:

  1. Install the updated pnet IP/UDP toolbox for MATLAB
    1. Checkout the source from /PlatformSupport/pnet (or svn co http://warpproject.org/svn/WARP/PlatformSupport/pnet)
      • The repository contains a compiled binary for Windows 7 64-bit
      • For other platforms, compile the pnet mex function
    2. Add the pnet folder to your MATLAB path. The pnet folder should contain pnet.m and th pnet.mex binary (i.e. pnet.mexw64)
    3. Verify pnet is recognized by running pnet('version'); on the MATLAB command line. The output should print the version number.
    4. Re-run the wl_setup function in M_Code_Reference. The final prompt will be to select which type of transport you want to use. If you have added a compatible, compiled pnet to your path, the script will list it as an option you can select. Note: simply re-running 'wl_setup' and selecting java is sufficient for switching back to the built-in java routines. You do not need to explicitly remove pnet from your MATLAB path.