doc/guides/nics/nfb.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2019 Cesnet
   3     Copyright 2019 Netcope Technologies
   4
   5 NFB poll mode driver library
   6 =================================
   7
   8 The NFB poll mode driver library implements support for the Netcope
   9 FPGA Boards (**NFB-40G2, NFB-100G2, NFB-200G2QL**) and Silicom **FB2CGG3** card,
  10 FPGA-based programmable NICs. The NFB PMD uses interface provided by the libnfb
  11 library to communicate with these cards over the nfb layer.
  12
  13 More information about the
  14 `NFB cards <http://www.netcope.com/en/products/fpga-boards>`_
  15 and used technology
  16 (`Netcope Development Kit <http://www.netcope.com/en/products/fpga-development-kit>`_)
  17 can be found on the `Netcope Technologies website <http://www.netcope.com/>`_.
  18
  19 .. note::
  20
  21    This driver has external dependencies.
  22    Therefore it is disabled in default configuration files.
  23    It can be enabled by setting ``CONFIG_RTE_LIBRTE_NFB_PMD=y``
  24    and recompiling.
  25
  26 .. note::
  27
  28    Currently the driver is supported only on x86_64 architectures.
  29    Only x86_64 versions of the external libraries are provided.
  30
  31 Prerequisites
  32 -------------
  33
  34 This PMD requires kernel modules which are responsible for initialization and
  35 allocation of resources needed for nfb layer function.
  36 Communication between PMD and kernel modules is mediated by libnfb library.
  37 These kernel modules and library are not part of DPDK and must be installed
  38 separately:
  39
  40 *  **libnfb library**
  41
  42    The library provides API for initialization of nfb transfers, receiving and
  43    transmitting data segments.
  44
  45 *  **Kernel modules**
  46
  47    * nfb
  48
  49    Kernel modules manage initialization of hardware, allocation and
  50    sharing of resources for user space applications.
  51
  52 Dependencies can be found here:
  53 `Netcope common <https://www.netcope.com/en/company/community-support/dpdk-libsze2#NFB>`_.
  54
  55 Versions of the packages
  56 ~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 The minimum version of the provided packages:
  59
  60 * for DPDK from 19.05
  61
  62 Configuration
  63 -------------
  64
  65 These configuration options can be modified before compilation in the
  66 ``.config`` file:
  67
  68 *  ``CONFIG_RTE_LIBRTE_NFB_PMD`` default value: **n**
  69
  70    Value **y** enables compilation of nfb PMD.
  71
  72
  73 Timestamps
  74
  75 The PMD supports hardware timestamps of frame receipt on physical network interface. In order to use
  76 the timestamps, the hardware timestamping unit must be enabled (follow the documentation of the NFB
  77 products) and the device argument `timestamp=1` must be used.
  78
  79 .. code-block:: console
  80
  81     $RTE_TARGET/app/testpmd -w b3:00.0,timestamp=1 <other EAL params> -- <testpmd params>
  82
  83 When the timestamps are enabled with the *devarg*, a timestamp validity flag is set in the MBUFs
  84 containing received frames and timestamp is inserted into the `rte_mbuf` struct.
  85
  86 The timestamp is an `uint64_t` field. Its lower 32 bits represent *seconds* portion of the timestamp
  87 (number of seconds elapsed since 1.1.1970 00:00:00 UTC) and its higher 32 bits represent
  88 *nanosecond* portion of the timestamp (number of nanoseconds elapsed since the beginning of the
  89 second in the *seconds* portion.
  90
  91
  92 Using the NFB PMD
  93 ----------------------
  94
  95 Kernel modules have to be loaded before running the DPDK application.
  96
  97 NFB card architecture
  98 ---------------------
  99
 100 The NFB cards are multi-port multi-queue cards, where (generally) data from any
 101 Ethernet port may be sent to any queue.
 102 They are represented in DPDK as a single port.
 103
 104 NFB-200G2QL card employs an add-on cable which allows to connect it to two
 105 physical PCI-E slots at the same time (see the diagram below).
 106 This is done to allow 200 Gbps of traffic to be transferred through the PCI-E
 107 bus (note that a single PCI-E 3.0 x16 slot provides only 125 Gbps theoretical
 108 throughput).
 109
 110 Although each slot may be connected to a different CPU and therefore to a different
 111 NUMA node, the card is represented as a single port in DPDK. To work with data
 112 from the individual queues on the right NUMA node, connection of NUMA nodes on
 113 first and last queue (each NUMA node has half of the queues) need to be checked.
 114
 115 .. figure:: img/szedata2_nfb200g_architecture.*
 116     :align: center
 117
 118     NFB-200G2QL high-level diagram
 119
 120 Limitations
 121 -----------
 122
 123 Driver is usable only on Linux architecture, namely on CentOS.
 124
 125 Since a card is always represented as a single port, but can be connected to two
 126 NUMA nodes, there is need for manual check where master/slave is connected.
 127
 128 Example of usage
 129 ----------------
 130
 131 Read packets from 0. and 1. receive queue and write them to 0. and 1.
 132 transmit queue:
 133
 134 .. code-block:: console
 135
 136    $RTE_TARGET/app/testpmd -l 0-3 -n 2 \
 137    -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2 -i -a
 138
 139 Example output:
 140
 141 .. code-block:: console
 142
 143    [...]
 144    EAL: PCI device 0000:06:00.0 on NUMA socket -1
 145    EAL:   probe driver: 1b26:c1c1 net_nfb
 146    PMD: Initializing NFB device (0000:06:00.0)
 147    PMD: Available DMA queues RX: 8 TX: 8
 148    PMD: NFB device (0000:06:00.0) successfully initialized
 149    Interactive-mode selected
 150    Auto-start selected
 151    Configuring Port 0 (socket 0)
 152    Port 0: 00:11:17:00:00:00
 153    Checking link statuses...
 154    Port 0 Link Up - speed 10000 Mbps - full-duplex
 155    Done
 156    Start automatic packet forwarding
 157      io packet forwarding - CRC stripping disabled - packets/burst=32
 158      nb forwarding cores=2 - nb forwarding ports=1
 159      RX queues=2 - RX desc=128 - RX free threshold=0
 160      RX threshold registers: pthresh=0 hthresh=0 wthresh=0
 161      TX queues=2 - TX desc=512 - TX free threshold=0
 162      TX threshold registers: pthresh=0 hthresh=0 wthresh=0
 163      TX RS bit threshold=0 - TXQ flags=0x0
 164    testpmd>