Subject: ITP: rdma-utils -- Infiniband Kernel Module Initializer and port config tool
Package: wnpp
Owner: Talat Batheesh <talatb@mellanox.com>
Severity: wishlist

* Package name    : rdma-utils
  Version         : 4.1.1
  Upstream Author : Doug Ledford <dledford@redhat.com>
* URL             : https://github.com/Mellanox/rdma-utils
* License         : GPLv2+
  Programming Lang: Bourne Shell, Bash
  Description     : Infiniband Kernel Module Initializer and port config tool

Overview
rdma-utils package allows InfiniBand users to manage user-level RDMA protocols that
want to be loaded by default, change port type to Ethernet or InfiniBand and
manage the SR-IOV for Mellanox ConnectX family adapret cards.
The rdma service is user space initialization scripts for the kernel InfiniBand
/iWARP drivers.
It reads the /etc/rdma/rdma.conf file to find out which kernel-level and
user-level RDMA protocols the administrator wants to be loaded by default. This
 file can be modified to turn various drivers ON or OFF.
The various drivers that can be enabled and disabled are:
·      IPoIB - an IP network emulation layer that allows IP applications to run
        over InfiniBand networks.
·      SRP - the SCSI Request Protocol. It allows a machine to mount a remot
        drive or drive array that is exported via the SRP protocol on the
        machine as though it were a local hard disk.
·      SRPT - the target mode, or server mode, of the SRP potocol. This load
        the kernel support necessary for exporting a drive or drive array for
        other machines to mount as though it were local on their machine.
        Further configuration of the target mode support is required before any
        devices will actually be exported.
·      iSER - a low-level driver for the general iSCSI layer of the Linux kerne
        that provides transport over InfiniBand networks for iSCSI devices.
·      RDS - the Reliable Datagram Service in the Linux kernel.

Starting up the rdma service is done automatically. When RDMA capable hardware,
whether InfiniBand or iWARP or RoCE/IBoE is detected, udev instructs systemd to
start the rdma service. The rdma service can be enabled to be set as ON all the
time but it is not mandatory to do so.
The rdma package provides the /etc/udev.d/rules.d/70-persistent-ipoib.rules file
which is used to rename IPoIB devices default names (such as ib0 and ib1) to a
more descriptive names. Users must edit this file to change how their devices
are named.
This package will be maintained under the umbrella of "OFED and Debian
Development and Discussion team", project name "OFED Infiniband Distribution".


 * Configuring Mellanox Cards Ports for Ethernet Operation

Certain Mellanox ConnectX adapter cards (which use the mlx4 driver) can be configured
to run in either InfiniBand or Ethernet mode (default InfiniBand).
To set the mode:
        1. Find the right PCI device ID of your adapter card.  For information
           on how to, follow the instruction in the file /etc/rdma/mlx4.conf.
        2.Create a line in the file using that device ID and the requested port
          type.
        3.Rebuild the initramfs to make sure the updated port settings are
        copied into the initramfs.

 * RDMA Configuration File(s)

The rdma service loads the configuration from /etc/rdma/rdma.conf file which
controls which modules will be loaded during the service startup and some
attributes about the RDMA modules. The following parameters are supported:
+------------------+----------------------------------+-----------------------+
|   Parameter name |       Description                |  Supported values     |
+-----------------------------------------------------------------------------+
|IPOIB_LOAD        | Load IPoIB module                | yes/no                |
+-----------------------------------------------------------------------------+
|SRP_LOAD          | Load SRP initiator module        | yes/no                |
+-----------------------------------------------------------------------------+
|SRPT_LOAD         | Load SRP target module           | yes/no                |
+-----------------------------------------------------------------------------+
|ISER_LOAD         | Load ISER initiator module       | yes/no                |
+-----------------------------------------------------------------------------+
|RDS_LOAD          | Load RDS module                  | yes/no                |
+-----------------------------------------------------------------------------+
|FIXUP_MTRR_REGS   | Modify the system mtrr registers | yes/no                |
+------------------+----------------------------------+-----------------------+


 * Starting the RDMA Services

Loading/unloading the RDMA drivers is done using the Infiniband Kernel Module
Initializer and port config tool.
        - To load/unload the rdma service:
        [root@localhost]# systemctl start/stop rdma.service
        - To start the rdma service automatically when the operating system is
          loaded:
        [root@localhost]# systemctl enable rdma