wiki:WARPLab/MEX

Version 5 (modified by welsh, 10 years ago) (diff)

--

WARPLab MEX Compliation

In order to provide better performance, the WARPLab reference design includes a MEX implementation (wl_mex_udp_transport) of the WARPLab UDP transport. This implementation provides significantly higher performance than both the java and pnet transports used in previous WARPLab releases.

The wl_mex_udp_transport C code must be compiled using MATLAB's MEX tools before it can be used with the WARPLab reference design. MATLAB uses the Microsoft Visual C compiler for creating MEX libraries in Windows. Please refer to the How-To Compile MEX guide for pointers setting up your MATLAB environment for compiling MEX functions.

Once your MATLAB environment is ready for MEX compilation, please follow the instructions below to complete the installation of the wl_mex_udp_transport.

WARPLab MEX UDP Transport

By default, WARPLab will use built-in java routines for performing network I/O. However, this has some performance limitations as can be seen by our Read IQ / Write IQ performance benchmarks. Therefore, we have developed a custom WARPLab MEX UDP transport in order to provide a high performance transport for data transfer operations. The WARPLab MEX UDP transport can provide dramatically faster performance while leaving the usage of WARPLab otherwise identical.

The source files for the WARPLab MEX UDP transport can be found at:

To install the WARPLab MEX UDP Transport, please perform the following steps:

NOTE: Make sure you are downloading the WARPLab 7.3.0 (or later) release, or your repository is updated to the WARPLab 7.3.0 (or later) release. In order to use this transport on your system, you must compile the wl_mex_udp_transport mex function (see How-To Compile MEX for more information).

NOTE: The wl_mex_udp_transport in WARPLab 7.3.0 only supports Windows operating systems. However, the transport in the repository has been updated to support both Windows and Unix/Mac operating systems. All command lines in this documentation have been updated to support the new version of the transport but are backward compatible with the WARPLab 7.3.0 release.

  1. Within MATLAB, change your directory to the M_Code_Reference directory that you unpacked as part of the WARPLab release.
  2. Run wl_setup in order to set up your MATLAB paths. When running wl_setup , you should only see the java transport available. If not, please check your paths to make sure there are no issues.
    • Now your paths should be set up to proceed. Run which wl_mex_udp_transport to check that you can see the mex files. You should see: <your WARPLab install dir>/M_Code_Reference/mex/wl_mex_udp_transport.m
  3. Run wl_mex_udp_transport from the MATLAB command line:
    >> wl_mex_udp_transport
    WARPLab wl_mex_udp_transport Setup
        Would you like [1] Manual (default) or [2] Automatic compliation?
        Selection: 
    
    • You have the ability to run either the manual or automatic compilation.

Manual Compilation

If you run the manual compilation, MATLAB will print out the compilation steps:

Manual Compliation Steps:  
    1) Please familiarize yourself with the process at: 
         http://warpproject.org/trac/wiki/WARPLab/MEX 
       to make sure your environment is set up properly. 
    2) Set up mex to choose your compiler.  (mex -setup) 
         1. Select "Yes" to have mex locate installed compilers 
         2. Select "Microsoft Visual C++ 2010 Express" 
         3. Select "Yes" to verify your selections 
    3) Change directory to M_Code_Reference/mex (cd mex) 
    4) Run the compile command: 
         mex -g -O wl_mex_udp_transport.c -lwsock32 -lKernel32 -DWIN32
    5) Re-run wl_setup and make sure that "WARPLab Mex UDP" is an available transport. 

Automatic Compilation

If you run the automatic compilation, the code will attempt to compile the mex using the compiler you installed from the How-To Compile MEX guide.

>> wl_mex_udp_transport
WARPLab wl_mex_udp_transport Setup
    Would you like [1] Manual (default) or [2] Automatic compliation?
    Selection: 2

Running Automatic Setup procedure: ...Done. 

***************************************************************
***************************************************************
Please re-run wl_setup to use your "WARPLab Mex UDP" transport.
***************************************************************
***************************************************************

If there are any issues, please follow the prompts to set up the compiler (ie you will be running mex -setup ) and then re-run wl_udp_mex_transport and the compilation should succeed.

Finalizing Your MEX install

Please make sure to re-run wl_setup so that you can choose the WARPLab MEX transport to use with WARPLab. You can verify that the transport is recognized by running wl_mex_udp_transport('version'); on the MATLAB command line. The output should print the version number. For example:

>> wl_mex_udp_transport('version');
Loaded wl_mex_udp_transport version 1.0.0a 
WARPLab MEX UDP Transport v1.0.0a (compiled Aug 21 2013 09:46:30)
Copyright 2013, Mango Communications. All rights reserved.
Distributed under the WARP license:  http://warpproject.org/license  

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 wl_mex_udp_transport from your MATLAB path.

NOTE: once you have correctly compiled your wl_mex_udp_transport, you will no longer be able to just run wl_udp_mex_transport . This will result in a usage error because now you need to use the functions within the transport.

Transport Documentation

From the MATLAB command line, you can run:

help wl_mex_udp_transport

to print out the help information as well as the usage. Also, the source code has been heavily commented to aid in understanding the transport.

If you have any additional questions, please let us know on the WARP forums.

pnet Toolbox

NOTE: The PNET toolbox will not be supported in WARPLab 7.4.0 or later.

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.