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