irdma RDMA FreeBSD* user space driver for Intel(R) Ethernet Controller E810
===========================================================================
September 20, 2022

Contents
========

- Prerequisites
- Building and Installation
- Testing
- Configuration
- Interoperability
- Known Issues
- Support

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


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

- All prerequisities for irdma kernel driver apply.


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

1. Untar irdma-<version>.tar.gz:
     tar -xf irdma-<version>.tar.gz
2. Copy libirdma dir into /usr/src/contrib/ofed/ directory:
     cp -r libirdma /usr/src/contrib/ofed/
3. Create /usr/src/lib/ofed/libirdma and copy lib_Makefile as Makefile into
   that directory:
     mkdir /usr/src/lib/ofed/libirdma
     cp lib_Makefile /usr/src/lib/ofed/libirdma/Makefile
4. Patch exisiting system user space code to accept libirdma for building:
     patch -d /usr/src < patches/intree_lib_compile.diff
5. Rebuild the ofed user space:
     cd /usr/src/lib/ofed
     make clean
     make
     make install
   Consider using -j parameter for faster compilation.
6. To take full advantage of ibv tools do:
     cd /usr/src/usr.bin/ofed/
     make clean
     make
     make install
   This will rebuild all tools that can be used with libirdma, i.e. ibv_devices
   and ibv_devinfo.

Testing
-------
1. When the irdma kernel driver is loaded, there are mutliple records when
   attempting to execute:
     sysctl sys.class.infiniband
   The libirdma working correctly can be verified with running ibv_devinfo or
   ibv_devices tools:
     ibv_devinfo
     ibv_devices
   Both should report irdma devices available.
2. See perftest_readme.txt to check details on how to perform verification with
   the perftest tool.
===============================================================================


Configuration
-------------

Interoperability
----------------
- irdma and libirdma versions
  Starting from irdma 1.1.3 there is a feature to check what version of irdma
  and libirdma is actually in use. Prior to that version the irdma notes the
  current version of kernel driver in dmesg, but it is done only on load and
  for cases when irdma is loaded for very long time the information can be
  lost.
  To check the current irdma version it is enough to use:
    sysctl dev.irdma<interface_number>.drv_ver
  To check current libirdma version, one may use shared function
  libirdma_query_device(). For example, a simple program used to determine the
  version can look like this:

    #include <stdio.h>
    #include <libirdma/irdma_uquery.h>

    int main()
    {
            struct libirdma_device attrs;

            libirdma_query_device(NULL, &attrs);
            printf("libirdma version in use: %s %zu %d\n",
    	           attrs.lib_ver, sizeof(attrs.lib_ver),
    	           attrs.query_ver);

            return 0;
    }

  And it can be compiled using:
    cc -I/usr/src/contrib/ofed/ -lirdma \
       libirdma_ver_test.c -o libirdma_ver_test
  Please note, in case of any problems with user space tools, it is always
  worth checking whether the versions of kernel driver and libirdma match.

Known Issues
------------
- During extensive traffic in RoCEv2 mode with multiple QPs CQP Error 8029
  may occur. This can result in kernel panic.
- During extensive traffic in RoCEv2 mode using send operations multiple
  AE 0x50a errors may occur, even when PFC is enabled and correctly configured.
- During traffic in RoCEv2 mode, using large number of QPs (>64) a PE
  Critical Error may occur. In such circumstances the card may become
  inoperational, and reboot is required to restore RDMA capability.

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



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


License
-------

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
----------

(c) Intel Corporation. Intel, the Intel logo, and other Intel marks are
trademarks of Intel Corporation or its subsidiaries. 
Other names and brands may be claimed as the property of others. 


