doc/guides/nics/szedata2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2015 - 2016 CESNET
   3
   4 SZEDATA2 poll mode driver library
   5 =================================
   6
   7 The SZEDATA2 poll mode driver library implements support for the Netcope
   8 FPGA Boards (**NFB-40G2, NFB-100G2, NFB-200G2QL**) and Silicom **FB2CGG3** card,
   9 FPGA-based programmable NICs. The SZEDATA2 PMD uses interface provided by the libsze2
  10 library to communicate with the NFB cards over the sze2 layer.
  11
  12 More information about the
  13 `NFB cards <http://www.netcope.com/en/products/fpga-boards>`_
  14 and used technology
  15 (`Netcope Development Kit <http://www.netcope.com/en/products/fpga-development-kit>`_)
  16 can be found on the `Netcope Technologies website <http://www.netcope.com/>`_.
  17
  18 .. note::
  19
  20    This driver has external dependencies.
  21    Therefore it is disabled in default configuration files.
  22    It can be enabled by setting ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y``
  23    and recompiling.
  24
  25 .. note::
  26
  27    Currently the driver is supported only on x86_64 architectures.
  28    Only x86_64 versions of the external libraries are provided.
  29
  30 Prerequisites
  31 -------------
  32
  33 This PMD requires kernel modules which are responsible for initialization and
  34 allocation of resources needed for sze2 layer function.
  35 Communication between PMD and kernel modules is mediated by libsze2 library.
  36 These kernel modules and library are not part of DPDK and must be installed
  37 separately:
  38
  39 *  **libsze2 library**
  40
  41    The library provides API for initialization of sze2 transfers, receiving and
  42    transmitting data segments.
  43
  44 *  **Kernel modules**
  45
  46    * combo6core
  47    * combov3
  48    * szedata2
  49    * szedata2_cv3 or szedata2_cv3_fdt
  50
  51    Kernel modules manage initialization of hardware, allocation and
  52    sharing of resources for user space applications.
  53
  54 Information about getting the dependencies can be found `here
  55 <http://www.netcope.com/en/company/community-support/dpdk-libsze2>`_.
  56
  57 Versions of the packages
  58 ~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 The minimum version of the provided packages:
  61
  62 * for DPDK from 18.05: **4.4.1**
  63
  64 * for DPDK up to 18.02 (including): **3.0.5**
  65
  66 Configuration
  67 -------------
  68
  69 These configuration options can be modified before compilation in the
  70 ``.config`` file:
  71
  72 *  ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2`` default value: **n**
  73
  74    Value **y** enables compilation of szedata2 PMD.
  75
  76 Using the SZEDATA2 PMD
  77 ----------------------
  78
  79 From DPDK version 16.04 the type of SZEDATA2 PMD is changed to PMD_PDEV.
  80 SZEDATA2 device is automatically recognized during EAL initialization.
  81 No special command line options are needed.
  82
  83 Kernel modules have to be loaded before running the DPDK application.
  84
  85 NFB card architecture
  86 ---------------------
  87
  88 The NFB cards are multi-port multi-queue cards, where (generally) data from any
  89 Ethernet port may be sent to any queue.
  90 They were historically represented in DPDK as a single port.
  91
  92 However, the new NFB-200G2QL card employs an add-on cable which allows to connect
  93 it to two physical PCI-E slots at the same time (see the diagram below).
  94 This is done to allow 200 Gbps of traffic to be transferred through the PCI-E
  95 bus (note that a single PCI-E 3.0 x16 slot provides only 125 Gbps theoretical
  96 throughput).
  97
  98 Since each slot may be connected to a different CPU and therefore to a different
  99 NUMA node, the card is represented as two ports in DPDK (each with half of the
 100 queues), which allows DPDK to work with data from the individual queues on the
 101 right NUMA node.
 102
 103 .. figure:: img/szedata2_nfb200g_architecture.*
 104     :align: center
 105
 106     NFB-200G2QL high-level diagram
 107
 108 Limitations
 109 -----------
 110
 111 The SZEDATA2 PMD does not support operations related to Ethernet ports
 112 (link_up, link_down, set_mac_address, etc.).
 113
 114 NFB cards employ multiple Ethernet ports.
 115 Until now, Ethernet port-related operations were performed on all of them
 116 (since the whole card was represented as a single port).
 117 With NFB-200G2QL card, this is no longer viable (see above).
 118
 119 Since there is no fixed mapping between the queues and Ethernet ports, and since
 120 a single card can be represented as two ports in DPDK, there is no way of
 121 telling which (if any) physical ports should be associated with individual
 122 ports in DPDK.
 123
 124 Example of usage
 125 ----------------
 126
 127 Read packets from 0. and 1. receive channel and write them to 0. and 1.
 128 transmit channel:
 129
 130 .. code-block:: console
 131
 132    $RTE_TARGET/app/testpmd -l 0-3 -n 2 \
 133    -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2 -i -a
 134
 135 Example output:
 136
 137 .. code-block:: console
 138
 139    [...]
 140    EAL: PCI device 0000:06:00.0 on NUMA socket -1
 141    EAL:   probe driver: 1b26:c1c1 rte_szedata2_pmd
 142    PMD: Initializing szedata2 device (0000:06:00.0)
 143    PMD: SZEDATA2 path: /dev/szedataII0
 144    PMD: Available DMA channels RX: 8 TX: 8
 145    PMD: resource0 phys_addr = 0xe8000000 len = 134217728 virt addr = 7f48f8000000
 146    PMD: szedata2 device (0000:06:00.0) successfully initialized
 147    Interactive-mode selected
 148    Auto-start selected
 149    Configuring Port 0 (socket 0)
 150    Port 0: 00:11:17:00:00:00
 151    Checking link statuses...
 152    Port 0 Link Up - speed 10000 Mbps - full-duplex
 153    Done
 154    Start automatic packet forwarding
 155      io packet forwarding - CRC stripping disabled - packets/burst=32
 156      nb forwarding cores=2 - nb forwarding ports=1
 157      RX queues=2 - RX desc=128 - RX free threshold=0
 158      RX threshold registers: pthresh=0 hthresh=0 wthresh=0
 159      TX queues=2 - TX desc=512 - TX free threshold=0
 160      TX threshold registers: pthresh=0 hthresh=0 wthresh=0
 161      TX RS bit threshold=0 - TXQ flags=0x0
 162    testpmd>