i40iw Linux* Driver for Intel(R) Ethernet Connection X722
===============================================================================

November 9, 2016

===============================================================================

Contents
--------

- Prerequisites
- Building and Installation
- Testing
- Virtualization
- Interoperability
- RDMA Statistics
- Known Issues


================================================================================


Prerequisites
-------------

- OFED 3.18-2. Install with ./install.pl --all
- A Linux distro supported by OFED 3.18-2 (see docs\OFED_release_notes.txt in
    OFED 3.18-2 installation location)
- For RDMA PF driver (i40iw), compile and install i40e driver.
- For RDMA VF driver (i40iwvf), compile and install i40evf driver.

NOTE: Internet Wide Area RDMA Protocol (iWARP) is not supported with the
i40iwvf driver running on Microsoft* Hyper-V.


Building and Installation
-------------------------

1. Untar i40iw-<version>.tar.gz, i40iwvf-<version>.tar.gz and libi40iw-
  <version>.tar.gz.
2. Install the PF driver as follows:
    cd i40iw-<version> directory
    ./build.sh <absolute path to i40e driver directory>
      For example: ./build.sh /opt/i40e-1.6.14_rc5_X722
3. Install the VF driver as follows:
    cd i40iwvf-<version> directory
    ./build.sh <absolute path to i40evf driver directory>
      For example: ./build.sh /opt/i40evf-1.6.14_rc5_X722
4. Install user-space library as follows:
    cd libi40iw-<version>
    ./build.sh


Testing
-------

Perform the following steps to test the installation.

1. Start rping server on one system:
  rping -sdVa [server_IP]
2. Connect the client from a different system:
  rping -cdVa [server_IP]


================================================================================


Virtualization
--------------

To enable SR-IOV support, load i40iw with the following parameters
and then create VFs with i40e.

  resource_profile=2 max_rdma_vfs=<number of VFs with RDMA support (0-32)>

  For example:
  modprobe i40iw resource_profile=2 max_rdma_vfs=32

NOTE: Once the VFs are running, do not change the PF configuration.


Interoperability
----------------

To interoperate with Chelsio iWARP devices:

1. Load i40iw driver with parameter mpa_version set to 1.

  modprobe i40iw mpa_version=1

  If i40iw is loaded on system boot, create /etc/modprobe.d/i40iw.conf file
  with the following entry:

  options i40iw mpa_version=1

  Reload i40iw for the new parameter to take effect.

2. Load Chelsio T4/T5 RDMA driver (iw_cxgb4) with parameters
  c4iw_max_read_depth   set to 63 and dack_mode set to 0.

  modprobe iw_cxgb4 c4iw_max_read_depth=63 dack_mode=0

  If iw_cxgb4 is loaded on system boot, create /etc/modprobe.d/iw_cxgb4.conf
  file
  with the following entry:

  options iw_cxgb4 c4iw_max_read_depth=63 dack_mode=0

  Reload iw_cxgb4 for the new parameters to take effect.


RDMA Statistics
---------------

Use the following command to read RDMA Protocol statistics:
  cd /sys/class/infiniband/i40iw0/proto_stats; for f in *; do echo -n 
  "$f: "; cat "$f"; done; cd

The following counters will increment when RDMA applications are
transferring data over the network:
  - ipInReceives
  - tcpInSegs
  - tcpOutSegs 


================================================================================


Known Issues/Troubleshooting
----------------------------


Incompatible Drivers in initramfs
---------------------------------

There may be incompatible drivers in the initramfs image. You can either
update the image or remove the drivers from initramfs.

Specifically look for i40e, ib_addr, ib_cm, ib_core, ib_mad, ib_sa, ib_ucm,
ib_uverbs, iw_cm, rdma_cm, rdma_ucm in the output of the following command:
  lsinitrd |less
If you see any of those modules, rebuild initramfs with the following
command and include the name of the module in the "" list. Below is an
example:
  dracut --force --omit-drivers "i40e ib_addr ib_cm ib_core ib_mad ib_sa
  ib_ucm ib_uverbs iw_cm rdma_cm rdma_ucm"


================================================================================


Support
-------
For general information, go to the Intel support website at:
www.intel.com/support/

or the Intel Wired Networking project hosted by Sourceforge at:
http://sourceforge.net/projects/e1000

If an issue is identified with the released source code on a supported
kernel with a supported adapter, email the specific information related to the
issue to e1000-rdma@lists.sourceforge.net



================================================================================


* This software is available to you under a choice of one of two
* licenses. You may choose to be licensed under the terms of the GNU
* General Public License (GPL) Version 2, available from the file
* COPYING in the main directory of this source tree, or the
* OpenFabrics.org BSD license below:
*
*  Redistribution and use in source and binary forms, with or
*  without modification, are permitted provided that the following
*  conditions are met:
*
*  - Redistributions of source code must retain the above
*    copyright notice, this list of conditions and the following
*    disclaimer.
*
*  - Redistributions in binary form must reproduce the above
*    copyright notice, this list of conditions and the following
*    disclaimer in the documentation and/or other materials
*    provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
================================================================================



Trademarks
----------

Intel, Itanium, and Pentium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.


