aboutsummaryrefslogtreecommitdiffstats
path: root/src/plugins/rdma/rdma_doc.rst
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-10-08 14:05:35 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 23:22:20 +0000
commitf47122e07e1ecd0151902a3cabe46c60a99bee8e (patch)
tree0c28c0eca2cb17050d6f31fd8f0ca8f78299bf0d /src/plugins/rdma/rdma_doc.rst
parent1e4281223ab4d655b54496ae13fbdb68f867e351 (diff)
docs: convert plugins doc md->rst
Type: improvement Change-Id: I7e821cce1feae229e1be4baeed249b9cca658135 Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Diffstat (limited to 'src/plugins/rdma/rdma_doc.rst')
-rw-r--r--src/plugins/rdma/rdma_doc.rst102
1 files changed, 102 insertions, 0 deletions
diff --git a/src/plugins/rdma/rdma_doc.rst b/src/plugins/rdma/rdma_doc.rst
new file mode 100644
index 00000000000..c22ea550a75
--- /dev/null
+++ b/src/plugins/rdma/rdma_doc.rst
@@ -0,0 +1,102 @@
+RDMA (ibverb) device driver
+===========================
+
+This driver relies on Linux rdma-core (libibverb) userspace poll-mode
+driver to rx/tx Ethernet packets. Despite using the RDMA APIs, this is
+**not** about RDMA (no Infiniband, no RoCE, no iWARP), just pure
+traditional Ethernet packets.
+
+Maturity level
+--------------
+
+Under development: it should work, but has not been thoroughly tested.
+
+Supported Hardware
+------------------
+
+- Mellanox ConnectX-4
+- Mellanox ConnectX-5
+
+Features
+--------
+
+- bifurcation: MAC based flow steering for transparent sharing of a
+ single physical port between multiple virtual interfaces including
+ Linux netdev
+- multiqueue
+
+Security considerations
+-----------------------
+
+When creating a rdma interface, it will receive all packets to the MAC
+address attributed to the interface plus a copy of all broadcast and
+multicast traffic. The MAC address is under the control of VPP: **the
+user controlling VPP can divert all traffic of any MAC address to the
+VPP process, including the Linux netdev MAC address as long as it can
+create a rdma interface**. The rights to create a rdma interface are
+controlled by the access rights of the
+``/dev/infiniband/uverbs[0-9]+``\ device nodes.
+
+Quickstart
+----------
+
+1. Make sure the ``ib_uverbs`` module is loaded:
+
+::
+
+ ~# modprobe ib_uverbs
+
+2. In VPP, create a new rdma virtual interface tied to the Linux netdev
+ of the physical port you want to use (``enp94s0f0`` in this example):
+
+::
+
+ vpp# create int rdma host-if enp94s0f0 name rdma-0
+
+3. Use the interface as usual, e.g.:
+
+::
+
+ vpp# set int ip addr rdma-0 1.1.1.1/24
+ vpp# set int st rdma-0 up
+ vpp# ping 1.1.1.100`
+
+Containers support
+------------------
+
+It should work in containers as long as: - the ``ib_uverbs`` module is
+loaded - the device nodes ``/dev/infiniband/uverbs[0-9]+`` are usable
+from the container (but see `security
+considerations <#Security%20considerations>`__)
+
+SR-IOV VFs support
+------------------
+
+It should work on SR-IOV VFs the same way it does with PFs. Because of
+VFs security containment features, make sure the MAC address of the rdma
+VPP interface matches the MAC address assigned to the underlying VF. For
+example:
+
+::
+
+ host# echo 1 > /sys/class/infiniband/mlx5_0/device/sriov_numvfs
+ host# ip l set dev enp94s0f0 vf 0 mac 92:5d:f5:df:b1:6f spoof on trust off
+ host# ip l set dev enp94s0f2 up
+ vpp# create int rdma host-if enp94s0f2 name rdma-0
+ vpp# set int mac address rdma-0 92:5d:f5:df:b1:6f
+
+If you plan to use L2 features such as switching, make sure the
+underlying VF is configured in trusted mode and spoof-checking is
+disabled (of course, be aware of the `security
+considerations <#Security%20considerations>`__):
+
+::
+
+ host# ip l set dev enp94s0f0 vf 0 spoof off trust on
+
+Direct Verb mode
+----------------
+
+Direct Verb allows the driver to access the NIC HW RX/TX rings directly
+instead of having to go through libibverb and suffering associated
+overhead. It will be automatically selected if the adapter supports it.