****************************************
                                     README

                    ****************************************

                    Chelsio T5 OVS Offload Driver for Linux                 
           
                               
                            Version : 1.0.0.0 (Alpha)
                            Date    : 09/08/2016



Overview
================================================================================

Chelsio T5 OVS(Open vSwitch) offload driver package is for Chelsio's T5 Unified 
Wire adapters and installs the following components:

- OVS v2.5.0
- NIC driver v1.0.0.0
- Utilities (cxgbtool,t4perftune.sh)



================================================================================
  CONTENTS
================================================================================

- 1. Requirements
- 2. Supported Operating Systems
- 3. Supported Cards
- 4. How to Use
- 5. Support Documentation
- 6. Customer Support



1. Requirements
================================================================================

- Chelsio T5 40/10/1Gb adapter and system with supported platforms mentioned in 
  section 2.
- Before installing OVS, all the required dependencies should be installed first. 
  For the complete list of dependencies please visit 
  http://openvswitch.org/support/dist-docs-2.5/INSTALL.md.html



2. Supported Operating Systems
================================================================================

The Chelsio OVS Offload driver has been developed to run on 64-bit Linux 
platforms. Following is the list of supported distributions:

- RHEL 7.2,3.10.0-327.el7 
- RHEL 6.7,2.6.32-573.el6
- Kernel.org linux-4.1

Other kernel versions have not been tested and are not guaranteed to work.



3. Supported Cards
================================================================================

- T580-CR
- T580-LP-CR
- T540-CR
- T520-CR
- T520-LL-CR
- T520-BT



4. How to Use
================================================================================

4.1. Driver Installation
========================

a) Download the OVS offload driver package, Chelsio-OVS-x.x.x.x.tar.gz

b) Untar the tar-ball

   [root@host~]# tar -zxvfm Chelsio-OVS-x.x.x.x.tar.gz

c) Change your working directory to Chelsio-OVS-x.x.x.x

d) Build and install OVS and Chelsio drivers:

   [root@host~]# make install


4.2. Firmware Update
====================

The T5 firmware (v1.16.4.0) is installed on the system, typically in 
/lib/firmware/cxgb4, and the driver will auto-load the firmware if an update is
required. The kernel must be configured to enable userspace firmware loading 
support:

Device Drivers -> Generic Driver Options -> Userspace firmware loading support

The firmware version can be verified using ethtool:

   [root@host~]# ethtool -i <iface>


4.3. Configuration
==================

The following example explains the procedure to configure an OVS machine.

OVS TOPOLOGY
------------
                    ------------       
 --------          | OVS_Switch |          --------
| HOST A | ------->| eth2  eth3 |<------- | HOST B |
 --------           ------------           --------

"eth2" and "eth3" are Chelsio interfaces.
 
a) Load NIC (cxgb4) driver with hash-filter support:

   [root@host~]# modprobe cxgb4 use_ddr_filters=1

b) Bring up the Chelsio interfaces in promiscous mode:

   [root@host~]# ifconfig eth2 promisc up
   [root@host~]# ifconfig eth3 promisc up

c) Load Open vSwitch module:

   [root@host~]# modprobe openvswitch

d) Configure OVS

   [root@host~]# ovs-appctl exit
   [root@host~]# pkill -9 ovs
   [root@host~]# rm -rf /usr/local/etc/ovs-vswitchd.conf
   [root@host~]# rm -rf /usr/local/var/run/openvswitch/db.sock
   [root@host~]# rm -rf /usr/local/etc/openvswitch/conf.db
   [root@host~]# touch /usr/local/etc/ovs-vswitchd.conf
   [root@host~]# ovsdb-tool create /usr/local/etc/openvswitch/conf.db /root/Chelsio-OVS-x.x.x.x/src/openvswitch-2.5.0/vswitchd/vswitch.ovsschema
   [root@host~]# ovsdb-server /usr/local/etc/openvswitch/conf.db --remote=punix:/usr/local/var/run/openvswitch/db.sock \ 
   --remote=db:Open_vSwitch,Open_vSwitch,manager_options --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert --pidfile --detach --log-file
   [root@host~]# ovs-vsctl --no-wait init
   [root@host~]# export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
   [root@host~]# ovs-vswitchd --pidfile --detach

e) Create an OVS brige and add Chelsio interfaces to it:

   [root@host~]# ovs-vsctl add-br br0
   [root@host~]# sleep 2
   [root@host~]# ifconfig br0 up
   [root@host~]# ovs-vsctl add-port br0 eth2
   [root@host~]# sleep 5
   [root@host~]# ovs-vsctl add-port br0 eth3
   [root@host~]# sleep 5
   [root@host~]# ovs-vsctl show

f) Now ping from Host A to Host B to verify that OVS is configured successfully.

g) Stop the ping traffic and delete all the flows on switch:

   [root@host~]# ovs-ofctl del-flows br0

h) Create a new flow based on your requirement. In this case, we have configured
   to drop IPv4 TCP packets from host A (source IP 10.1.1.56) to host B 
   (destination IP 10.1.1.62)
  
   [root@host~]# ovs-ofctl add-flow br0 in_port=1,dl_type=0x800,nw_proto=6,nw_src=10.1.1.56,nw_dst=10.1.1.66,action=drop

i) Verify the flow dump:

   [root@host~]# ovs-ofctl dump-flows br0

   Start traffic from Host A to Host B and observe that the packets which match
   the flow will be dropped.


Setting Up OpenDaylight(ODL) with OVS
-------------------------------------

                  ------------
                  |     ODL    |
                  | Controller |
                   ------------
                         ^
                         |
                         |(private network)
                    ------------       
 --------          | OVS_Switch |          --------
| HOST A | ------->| eth2  eth3 |<------- | HOST B |
 --------           ------------           --------

On the ODL controller setup,

a) Download latest Java Development Kit from 
   http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

c) Untar the tar file. 

d) Create an entry in .bashrc which points to the extracted folder:

   export JAVA_HOME=<path>/jdk1.8.0_92
   export PATH=$PATH:$JAVA_HOME

e) Logout & log back in.

f) Download ODL controller pre-built zip package from https://www.opendaylight.org/software/downloads/hydrogen-base-10
  
g) Unzip the package and change your working directory to "opendaylight"

h) Run the script "run.sh" and wait for ~3 minutes for the controller to be setup.

i) Open a web browser and enter the address http://localhost:8080
   
   Login with username/password : admin/admin
  
j) On the OVS machine, add the bridge to the controller and disable in-band:

   [root@host ~]# ovs-vsctl set-controller br0 tcp:<ODL Controller IP>:6633
   [root@host ~]# ovs-vsctl set bridge br0 other-config:disable-in-band=true

k) Refresh the webpage on the ODL controller and you should see the OVS details.

l) Goto "Flows" tab, add and install a flow.

m) Verify the flow dump on the OVS machine:

   [root@host ~]# ovs-ofctl dump-flows br0

Run traffic between the hosts which matches the flow and verify if the n_packet 
counter increments.


4.4. Driver Uninstallation
==========================

Uninstall OVS and Chelsio drivers:

   [root@host~]# make uninstall



5. Support Documentation
================================================================================

The documentation for this release can be found in the Chelsio-OVS-x.x.x.x\docs\
directory.
It contains: 

- README
- Release Notes



6. Customer Support
================================================================================

Please contact Chelsio support at support@chelsio.com for any issues regarding 
the product.








********************************************************************************
Copyright (C) 2016 Chelsio Communications. All Rights Reserved.

The information in this document is furnished for informational use only, is
subject to change without notice, and should not be construed as a commitment by
Chelsio Communications. Chelsio Communications assumes no responsibility or
liability for any errors or inaccuracies that may appear in this document or any
software that may be provided in association with this document. Except as
permitted by such license, no part of this document may be reproduced, stored in
a retrieval system,or transmitted in any form or by any means without the
express written consent of Chelsio Communications.