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-***), FPGA-based programmable NICs.
   9 The SZEDATA2 PMD uses interface provided by the libsze2 library to communicate
  10 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 Configuration
  58 -------------
  59
  60 These configuration options can be modified before compilation in the
  61 ``.config`` file:
  62
  63 *  ``CONFIG_RTE_LIBRTE_PMD_SZEDATA2`` default value: **n**
  64
  65    Value **y** enables compilation of szedata2 PMD.
  66
  67 Using the SZEDATA2 PMD
  68 ----------------------
  69
  70 From DPDK version 16.04 the type of SZEDATA2 PMD is changed to PMD_PDEV.
  71 SZEDATA2 device is automatically recognized during EAL initialization.
  72 No special command line options are needed.
  73
  74 Kernel modules have to be loaded before running the DPDK application.
  75
  76 NFB card architecture
  77 ---------------------
  78
  79 The NFB cards are multi-port multi-queue cards, where (generally) data from any
  80 Ethernet port may be sent to any queue.
  81 They were historically represented in DPDK as a single port.
  82
  83 However, the new NFB-200G2QL card employs an addon cable which allows to connect
  84 it to two physical PCI-E slots at the same time (see the diagram below).
  85 This is done to allow 200 Gbps of traffic to be transferred through the PCI-E
  86 bus (note that a single PCI-E 3.0 x16 slot provides only 125 Gbps theoretical
  87 throughput).
  88
  89 Since each slot may be connected to a different CPU and therefore to a different
  90 NUMA node, the card is represented as two ports in DPDK (each with half of the
  91 queues), which allows DPDK to work with data from the individual queues on the
  92 right NUMA node.
  93
  94 .. figure:: img/szedata2_nfb200g_architecture.svg
  95     :align: center
  96
  97     NFB-200G2QL high-level diagram
  98
  99 Limitations
 100 -----------
 101
 102 The SZEDATA2 PMD does not support operations related to Ethernet ports
 103 (link_up, link_down, set_mac_address, etc.).
 104
 105 NFB cards employ multiple Ethernet ports.
 106 Until now, Ethernet port-related operations were performed on all of them
 107 (since the whole card was represented as a single port).
 108 With NFB-200G2QL card, this is no longer viable (see above).
 109
 110 Since there is no fixed mapping between the queues and Ethernet ports, and since
 111 a single card can be represented as two ports in DPDK, there is no way of
 112 telling which (if any) physical ports should be associated with individual
 113 ports in DPDK.
 114
 115 Example of usage
 116 ----------------
 117
 118 Read packets from 0. and 1. receive channel and write them to 0. and 1.
 119 transmit channel:
 120
 121 .. code-block:: console
 122
 123    $RTE_TARGET/app/testpmd -l 0-3 -n 2 \
 124    -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2 -i -a
 125
 126 Example output:
 127
 128 .. code-block:: console
 129
 130    [...]
 131    EAL: PCI device 0000:06:00.0 on NUMA socket -1
 132    EAL:   probe driver: 1b26:c1c1 rte_szedata2_pmd
 133    PMD: Initializing szedata2 device (0000:06:00.0)
 134    PMD: SZEDATA2 path: /dev/szedataII0
 135    PMD: Available DMA channels RX: 8 TX: 8
 136    PMD: resource0 phys_addr = 0xe8000000 len = 134217728 virt addr = 7f48f8000000
 137    PMD: szedata2 device (0000:06:00.0) successfully initialized
 138    Interactive-mode selected
 139    Auto-start selected
 140    Configuring Port 0 (socket 0)
 141    Port 0: 00:11:17:00:00:00
 142    Checking link statuses...
 143    Port 0 Link Up - speed 10000 Mbps - full-duplex
 144    Done
 145    Start automatic packet forwarding
 146      io packet forwarding - CRC stripping disabled - packets/burst=32
 147      nb forwarding cores=2 - nb forwarding ports=1
 148      RX queues=2 - RX desc=128 - RX free threshold=0
 149      RX threshold registers: pthresh=0 hthresh=0 wthresh=0
 150      TX queues=2 - TX desc=512 - TX free threshold=0
 151      TX threshold registers: pthresh=0 hthresh=0 wthresh=0
 152      TX RS bit threshold=0 - TXQ flags=0x0
 153    testpmd>